Class: RestEasy::Resource

Inherits:
Object
  • Object
show all
Extended by:
Dry::Configurable
Includes:
Types
Defined in:
lib/rest_easy/resource.rb

Defined Under Namespace

Classes: AttributeBlockDSL, ConfigureDSL, MetaCollector, ModelProxy, ShadowCopy

Constant Summary collapse

String =

Shadow Ruby’s built-in type names so that inside a regular class body (not Class.new blocks), ‘String`, `Integer`, etc. resolve to Dry::Types equivalents with coercion and constraint support.

Types::Coercible::String
Integer = 
Types::Coercible::Integer
Float = 
Types::Coercible::Float
Boolean = 
Types::Params::Bool
Date = 
Types::Params::Date
TYPE_MAP =

Map Ruby’s built-in classes to Dry::Types equivalents. Used by ‘attr` to resolve types passed from Class.new blocks where constant lookup doesn’t find our shadowed constants.

{
  ::String  => Types::Coercible::String,
  ::Integer => Types::Coercible::Integer,
  ::Float   => Types::Coercible::Float
}.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(model_data = {}) ⇒ Resource

Returns a new instance of Resource.



539
540
541
 
# File 'lib/rest_easy/resource.rb', line 539

def initialize(model_data = {})
  init_from_model(model_data)
end

Instance Attribute Details

#meta ⇒ Object (readonly)

Returns the value of attribute meta.



537
538
539
 
# File 'lib/rest_easy/resource.rb', line 537

def meta
  @meta
end

Class Method Details

.after_parse(&block) ⇒ Object 



345
346
347
 
# File 'lib/rest_easy/resource.rb', line 345

def after_parse(&block)
  @after_parse_hook = block
end

.after_serialise(&block) ⇒ Object 



353
354
355
 
# File 'lib/rest_easy/resource.rb', line 353

def after_serialise(&block)
  @after_serialise_hook = block
end

.all ⇒ Object 



447
448
449
450
 
# File 'lib/rest_easy/resource.rb', line 447

def all
  response = get(path: config.path.to_s)
  parse(response)
end

.all_attribute_definitions ⇒ Object 



369
370
371
372
 
# File 'lib/rest_easy/resource.rb', line 369

def all_attribute_definitions
  parent = superclass.respond_to?(:all_attribute_definitions) ? superclass.all_attribute_definitions : {}
  parent.merge(own_attribute_definitions)
end

.all_ignored_fields ⇒ Object 



378
379
380
381
 
# File 'lib/rest_easy/resource.rb', line 378

def all_ignored_fields
  parent = superclass.respond_to?(:all_ignored_fields) ? superclass.all_ignored_fields : []
  parent + own_ignored_fields
end

.attr(name_or_mapping, *args, &block) ⇒ Object

– attr ———————————————————-

Raises:



208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/rest_easy/resource.rb', line 208

def attr(name_or_mapping, *args, &block)
  # Determine attribute_api_name and attribute_model_name
  if name_or_mapping.is_a?(::Array)
    attribute_model_name = name_or_mapping[0].to_sym
    attribute_api_name = name_or_mapping[1].to_s
  else
    attribute_model_name = name_or_mapping.to_sym
    attribute_api_name = json_attribute_converter.serialise(attribute_model_name)
  end

  # Extract type (non-Symbol), flags (Symbols), and optional mapper object
  type = nil
  flags = []
  mapper = nil
  args.each do |arg|
    if arg.is_a?(::Symbol)
      flags << arg
    elsif arg.respond_to?(:parse) && arg.respond_to?(:serialise)
      mapper = arg
    else
      type = resolve_type(arg)
    end
  end

  raise AttributeError, "Attribute :#{attribute_model_name} must have a type" if type.nil?

  # Handle mapper object or block DSL for custom parse/serialise
  parse_block = nil
  serialise_block = nil
  source_fields = []
  target_fields = []
  if mapper
    parse_block = mapper.method(:parse)
    serialise_block = mapper.method(:serialise)

    # Introspect mapper method parameters the same way we do blocks.
    # This enables merge/split patterns with mapper objects.
    parse_params = parse_block.parameters.select { |ptype, _| ptype == :opt || ptype == :req }
    if parse_params.length > 1
      flags << :synthetic unless flags.include?(:synthetic)
      source_fields = parse_params.map { |_, pname| pname }
    end

    serialise_params = serialise_block.parameters.select { |ptype, _| ptype == :opt || ptype == :req }
    if serialise_params.length > 1
      target_fields = serialise_params.map { |_, pname| pname }
    end
  elsif block
    block_params = block.parameters.select { |ptype, _| ptype == :opt || ptype == :req }

    if block_params.any?
      # Bare block with params = implicit parse block.
      # The parameter names are API field references (resolved via convention).
      parse_block = block
      source_fields = block_params.map { |_, pname| pname }
      flags << :synthetic unless flags.include?(:synthetic)
    else
      # DSL block — evaluate to extract parse/serialise sub-blocks
      dsl = AttributeBlockDSL.new
      dsl.instance_eval(&block)
      parse_block = dsl.parse_block
      serialise_block = dsl.serialise_block

      # Introspect parse block parameters: if 2+ params, this is a
      # synthetic attribute. The parameter names are the source API fields
      # (e.g. |first_name, last_name| → source_fields [:first_name, :last_name]).
      if parse_block
        params = parse_block.parameters.select { |ptype, _| ptype == :opt || ptype == :req }
        if params.length > 1
          flags << :synthetic unless flags.include?(:synthetic)
          source_fields = params.map { |_, pname| pname }
        end
      end

      # Introspect serialise block parameters: if 2+ params, the parameter
      # names are model field references to gather during serialisation.
      if serialise_block
        params = serialise_block.parameters.select { |ptype, _| ptype == :opt || ptype == :req }
        if params.length > 1
          target_fields = params.map { |_, pname| pname }
        end
      end
    end
  end

  # Handle :key flag
  if flags.include?(:key)
    if @key_attribute_name && @key_attribute_name != attribute_model_name
      warn "Warning: :#{@key_attribute_name} already defined as :key, ignoring :#{attribute_model_name} as :key"
    else
      @key_attribute_name = attribute_model_name
    end
  end

  # Register attribute definition
  own_attribute_definitions[attribute_model_name] = Attribute.new(
    model_name: attribute_model_name,
    api_name: attribute_api_name,
    type:,
    flags:,
    parse_block:,
    serialise_block:,
    source_fields:,
    target_fields:
  )

  # Define accessor method on the class
  define_method(attribute_model_name) { @model_attributes[attribute_model_name] }
end

.attribute_convention(value = nil) ⇒ Object

– attribute_convention (deprecated) ——————————-



171
172
173
174
175
176
177
 
# File 'lib/rest_easy/resource.rb', line 171

def attribute_convention(value = nil)
  if value
    warn "RestEasy: attribute_convention is deprecated, use `configure { conversions.json_attributes = #{value.inspect} }` instead"
    config.conversions.json_attributes = value
  end
  json_attribute_converter
end

.attributes ⇒ Object

── Attribute introspection ────────────────────────────────────────



365
366
367
 
# File 'lib/rest_easy/resource.rb', line 365

def attributes
  all_attribute_definitions.keys
end

.attributes_with_flag(flag) ⇒ Object 



374
375
376
 
# File 'lib/rest_easy/resource.rb', line 374

def attributes_with_flag(flag)
  all_attribute_definitions.select { |_, attr_def| attr_def.flags.include?(flag) }
end

.before_parse(&block) ⇒ Object

– hooks ———————————————————



341
342
343
 
# File 'lib/rest_easy/resource.rb', line 341

def before_parse(&block)
  @before_parse_hook = block
end

.before_serialise(&block) ⇒ Object 



349
350
351
 
# File 'lib/rest_easy/resource.rb', line 349

def before_serialise(&block)
  @before_serialise_hook = block
end

.configure(&block) ⇒ Object 



138
139
140
141
 
# File 'lib/rest_easy/resource.rb', line 138

def configure(&block)
  dsl = ConfigureDSL.new(config)
  dsl.instance_eval(&block)
end

.create(instance) ⇒ Object 



460
461
462
463
464
465
466
 
# File 'lib/rest_easy/resource.rb', line 460

def create(instance)
  response = post(
    path: "#{config.path}",
    body: instance.serialise
  )
  parse(response)
end

.delete(id) ⇒ Object 



476
477
478
 
# File 'lib/rest_easy/resource.rb', line 476

def delete(id)
  parent.delete(path: "#{config.path}/#{id}")
end

.find(id) ⇒ Object

CRUD operations



442
443
444
445
 
# File 'lib/rest_easy/resource.rb', line 442

def find(id)
  response = get(path: "#{config.path}/#{id}")
  parse(response)
end

.get(path:, params: {}, headers: {}) ⇒ Object

HTTP primitives — delegate to the parent API module’s connection



482
483
484
485
486
 
# File 'lib/rest_easy/resource.rb', line 482

def get(path:, params: {}, headers: {})
  converter = query_parameter_converter
  converted_params = converter ? params.transform_keys { |k| converter.serialise(k) } : params
  parent.get(path:, params: converted_params, headers:)
end

.ignore(*api_field_names) ⇒ Object

– ignore ——————————————————–



333
334
335
336
337
 
# File 'lib/rest_easy/resource.rb', line 333

def ignore(*api_field_names)
  api_field_names.each do |field_name|
    own_ignored_fields << field_name.to_sym
  end
end

.json_attribute_converter ⇒ Object

– conversions —————————————————



155
156
157
158
159
160
161
 
# File 'lib/rest_easy/resource.rb', line 155

def json_attribute_converter
  Conventions.resolve(
    config.conversions.json_attributes ||
    parent&.config&.conversions&.json_attributes ||
    Conventions::DEFAULT
  )
end

.key(attr_name, type = nil, *flags) ⇒ Object

– key ———————————————————–



320
321
322
323
324
325
326
327
328
329
 
# File 'lib/rest_easy/resource.rb', line 320

def key(attr_name, type = nil, *flags)
  if @key_attribute_name
    warn "Warning: key already defined as :#{@key_attribute_name}, overriding with :#{attr_name}"
  end
  if type
    self.attr(attr_name, type, *flags, :key)
  else
    self.attr(attr_name, *flags, :key)
  end
end

.key_attribute_name ⇒ Object 



383
384
385
386
 
# File 'lib/rest_easy/resource.rb', line 383

def key_attribute_name
  @key_attribute_name ||
    (superclass.respond_to?(:key_attribute_name) ? superclass.key_attribute_name : nil)
end

.metadata(**kwargs) ⇒ Object

– metadata ——————————————————



145
146
147
148
149
150
151
 
# File 'lib/rest_easy/resource.rb', line 145

def metadata(**kwargs)
  if kwargs.any?
    own_metadata_defaults.merge!(kwargs)
  else
    all_metadata_defaults
  end
end

.parse(api_data) ⇒ Object

── Class-level operations ─────────────────────────────────────────



417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
 
# File 'lib/rest_easy/resource.rb', line 417

def parse(api_data)
  meta_collector = MetaCollector.new

  hook = resolve_before_parse_hook
  if hook
    api_data = instance_exec(api_data, meta_collector, &hook)
  end

  collected_meta = meta_collector.to_h

  if api_data.is_a?(::Array)
    api_data.map { |item| allocate.tap { |instance| instance.send(:init_from_api, item, collected_meta) } }
  else
    allocate.tap { |instance| instance.send(:init_from_api, api_data, collected_meta) }
  end
end

.post(path:, body: nil, headers: {}) ⇒ Object 



488
489
490
 
# File 'lib/rest_easy/resource.rb', line 488

def post(path:, body: nil, headers: {})
  parent.post(path:, body:, headers:)
end

.put(path:, body: nil, headers: {}) ⇒ Object 



492
493
494
 
# File 'lib/rest_easy/resource.rb', line 492

def put(path:, body: nil, headers: {})
  parent.put(path:, body:, headers:)
end

.query_parameter_converter ⇒ Object 



163
164
165
166
167
 
# File 'lib/rest_easy/resource.rb', line 163

def query_parameter_converter
  convention = config.conversions.query_parameters ||
               parent&.config&.conversions&.query_parameters
  convention && Conventions.resolve(convention)
end

.resolve_after_parse_hook ⇒ Object 



400
401
402
403
 
# File 'lib/rest_easy/resource.rb', line 400

def resolve_after_parse_hook
  @after_parse_hook ||
    (superclass.respond_to?(:resolve_after_parse_hook) ? superclass.resolve_after_parse_hook : nil)
end

.resolve_after_serialise_hook ⇒ Object 



410
411
412
413
 
# File 'lib/rest_easy/resource.rb', line 410

def resolve_after_serialise_hook
  @after_serialise_hook ||
    (superclass.respond_to?(:resolve_after_serialise_hook) ? superclass.resolve_after_serialise_hook : nil)
end

.resolve_before_parse_hook ⇒ Object

── Hook lookup (walks ancestor chain) ─────────────────────────────



395
396
397
398
 
# File 'lib/rest_easy/resource.rb', line 395

def resolve_before_parse_hook
  @before_parse_hook ||
    (superclass.respond_to?(:resolve_before_parse_hook) ? superclass.resolve_before_parse_hook : nil)
end

.resolve_before_serialise_hook ⇒ Object 



405
406
407
408
 
# File 'lib/rest_easy/resource.rb', line 405

def resolve_before_serialise_hook
  @before_serialise_hook ||
    (superclass.respond_to?(:resolve_before_serialise_hook) ? superclass.resolve_before_serialise_hook : nil)
end

.save(instance) ⇒ Object 



452
453
454
455
456
457
458
 
# File 'lib/rest_easy/resource.rb', line 452

def save(instance)
  if instance.meta.new?
    create(instance)
  else
    update(instance)
  end
end

.settings(&block) ⇒ Object

– settings ——————————————————-



132
133
134
135
136
 
# File 'lib/rest_easy/resource.rb', line 132

def settings(&block)
  return super() unless block

  class_eval(&block)
end

.stub(**model_data) ⇒ Object 



434
435
436
437
438
 
# File 'lib/rest_easy/resource.rb', line 434

def stub(**model_data)
  defaults = stub_defaults || {}
  data = defaults.merge(model_data)
  allocate.tap { |instance| instance.send(:init_from_model, data) }
end

.stub_defaults ⇒ Object 



388
389
390
391
 
# File 'lib/rest_easy/resource.rb', line 388

def stub_defaults
  parent = superclass.respond_to?(:stub_defaults) ? superclass.stub_defaults : {}
  (parent || {}).merge(@stub_defaults || {})
end

.update(instance) ⇒ Object 



468
469
470
471
472
473
474
 
# File 'lib/rest_easy/resource.rb', line 468

def update(instance)
  response = put(
    path: "#{config.path}/#{instance.unique_id}",
    body: instance.serialise
  )
  parse(response)
end

.with_stub(**defaults) ⇒ Object

– with_stub —————————————————–



359
360
361
 
# File 'lib/rest_easy/resource.rb', line 359

def with_stub(**defaults)
  @stub_defaults = defaults
end

Instance Method Details

#==(other) ⇒ Object Also known as: eql? 



649
650
651
652
 
# File 'lib/rest_easy/resource.rb', line 649

def ==(other)
  other.is_a?(self.class) && self.class == other.class &&
    @model_attributes == other.send(:model_attributes_hash)
end

#__changes__ ⇒ Object 



577
578
579
 
# File 'lib/rest_easy/resource.rb', line 577

def __changes__
  @changes || {}
end

#api ⇒ Object 



547
548
549
 
# File 'lib/rest_easy/resource.rb', line 547

def api
  ShadowCopy.new(@api_data)
end

#config ⇒ Object

Delegate class-level config so hooks can call it via instance_exec



533
534
535
 
# File 'lib/rest_easy/resource.rb', line 533

def config
  self.class.config
end

#hash ⇒ Object 



656
657
658
 
# File 'lib/rest_easy/resource.rb', line 656

def hash
  [self.class, @model_attributes].hash
end

#model ⇒ Object 



543
544
545
 
# File 'lib/rest_easy/resource.rb', line 543

def model
  ModelProxy.new(@model_attributes)
end

#serialise ⇒ Object 



581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
 
# File 'lib/rest_easy/resource.rb', line 581

def serialise
  klass = self.class

  # Run before_serialise hook on the instance
  # Input: model_attributes. Side-effect only; return value ignored.
  hook = klass.resolve_before_serialise_hook
  instance_exec(@model_attributes, &hook) if hook

  result = {}

  # Serialise all attributes
  klass.all_attribute_definitions.each do |_model_name, attr_def|
    next if attr_def.read_only?
    value = @model_attributes[attr_def.model_name]

    if attr_def.target_fields.any?
      # Multi-param serialise: gather model values by param names, splat into block
      model_values = attr_def.target_fields.map { |fn| @model_attributes[fn] }
      result[attr_def.api_name] = attr_def.serialise_value(*model_values)
    elsif attr_def.source_fields.any?
      serialised = attr_def.serialise_value(value)
      if serialised.is_a?(::Array)
        # Array return: zip with source field API names
        convention = klass.json_attribute_converter
        attr_def.source_fields.zip(serialised).each do |field_name, field_value|
          api_key = convention.serialise(field_name)
          result[api_key] = field_value
        end
      elsif serialised.is_a?(::Hash)
        # Hash return: merge into result
        result.merge!(serialised)
      else
        result[attr_def.api_name] = serialised
      end
    else
      result[attr_def.api_name] = attr_def.serialise_value(value)
    end
  end

  # Merge ignored fields from shadow copy
  if @api_data && !@api_data.empty?
    known_api_names = klass.all_attribute_definitions.values.map(&:api_name)
    @api_data.each do |api_key, value|
      unless known_api_names.include?(api_key) || result.key?(api_key)
        result[api_key] = value
      end
    end
  end

  # Run after_serialise hook on the instance
  # Input: serialised_data, model. Output: final serialised_data.
  hook = klass.resolve_after_serialise_hook
  if hook
    result = instance_exec(result, model, &hook)
  end

  result
end

#to_api ⇒ Object 



645
646
647
 
# File 'lib/rest_easy/resource.rb', line 645

def to_api
  ::JSON.generate(serialise)
end

#to_json(*_args) ⇒ Object 



640
641
642
643
 
# File 'lib/rest_easy/resource.rb', line 640

def to_json(*_args)
  model_hash = @model_attributes.transform_keys(&:to_s)
  ::JSON.generate(model_hash)
end

#unique_id ⇒ Object 



551
552
553
554
 
# File 'lib/rest_easy/resource.rb', line 551

def unique_id
  key_name = self.class.key_attribute_name
  key_name ? @model_attributes[key_name] : nil
end

#update(changes = {}, **kwargs) ⇒ Object 



556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
 
# File 'lib/rest_easy/resource.rb', line 556

def update(changes = {}, **kwargs)
  changes = changes.merge(kwargs) unless kwargs.empty?
  return self if changes.empty?

  klass = self.class
  coerced = {}
  changes.each do |attr_name, value|
    attr_def = klass.all_attribute_definitions[attr_name]
    coerced[attr_name] = if attr_def && !value.nil?
      attr_def.coerce(value)
    else
      value
    end
  end

  new_model = @model_attributes.merge(coerced)
  new_instance = self.class.allocate
  new_instance.send(:init_from_update, new_model, @api_data, coerced)
  new_instance
end