Module: TypedEAV::ScopeTuple

Defined in:
lib/typed_eav/scope_tuple.rb

Overview

Localized semantics for the ‘(scope, parent_scope)` tuple.

Five files used to smear tuple shape/coercion/invariant logic across themselves (‘lib/typed_eav.rb`, `Config`, `Partition`, `HasTypedEav#resolve_scope`, `Field::Base#for_entity`). This module gathers them in one place:

  • ‘normalize_permissive(value)` — the v0.1.x-BC scalar-friendly coercer used by the `with_scope` block surface and by callers that already know they may receive a loose value (single scalar, AR record, or 2-element Array). Mirrors what `TypedEAV.normalize_scope` did before this refactor; the public method is now a 1-line BC alias to this.

  • ‘normalize_strict(value)` — the contract-surface coercer used by `TypedEAV.current_scope` when consuming a configured `Config.scope_resolver` return. Bare scalars / 1-element / 3-element Arrays raise `ArgumentError` — this is the Phase-1 strict-contract chokepoint that makes a misshaped resolver fail loudly instead of silently coercing.

  • ‘invariant_satisfied?(scope, parent_scope)` — Boolean orphan-parent check. Returns `false` only when `parent_scope` is present and `scope` is blank (the dead-letter shape: a parent-scope predicate with no scope predicate). Each caller picks its own response policy (raise / AR error / silent narrow) on a `false` result; this helper never raises.

The split between permissive and strict normalization is the Phase-1 asymmetric contract preserved verbatim: ‘with_scope` block input is BC-permissive (scalars are sugar for `[scalar, nil]`), `scope_resolver` callable return is strict (scalars are a contract violation).

Class Method Summary collapse

Class Method Details

.invariant_satisfied?(scope, parent_scope) ⇒ Boolean

Orphan-parent invariant predicate. Returns ‘true` when the tuple is internally coherent, `false` ONLY when `parent_scope` is present while `scope` is blank — the dead-letter shape that cannot match any row under the partition predicates.

Truth table:

(nil, nil)     → true
("t1", nil)    → true
("t1", "w1")   → true
(nil, "w1")    → false
("",  "w1")    → false   (empty string treated as blank on scope axis)
(nil, "")      → true    (empty string treated as blank on parent axis)

Callers each pick their own response policy on a false result: ‘Partition.visible_fields` raises `ArgumentError`; `Field`’s model validator adds an AR error; ‘HasTypedEAV#resolve_scope` silently narrows the query. Returning a Boolean (not raising) keeps the per-caller decision local.

Returns:

  • (Boolean) 


98
99
100
101
102
 
# File 'lib/typed_eav/scope_tuple.rb', line 98

def invariant_satisfied?(scope, parent_scope)
  return true if parent_scope.blank?

  scope.present?
end

.normalize_permissive(value) ⇒ Object

BC-permissive normalizer for ‘with_scope` block input and explicit tuple inputs. Always returns either `nil` or a 2-element tuple `[scope, parent_scope]` where each element is a `String` or `nil`.

Accepted inputs:

  • ‘nil` → `nil` (sentinel: nothing resolved).

  • ‘[a, b]` (2-element Array) → `[normalize_one(a), normalize_one(b)]`. Canonical Phase-1 input shape. `[scope, nil]` is the “scope-only” tuple; `[nil, “ps1”]` (orphan-parent) is intentionally accepted at this layer — orphan-parent rejection happens at the calling site (Field validator → AR error, Partition query → ArgumentError, resolve_scope → silent narrow). Keeping normalize permissive lets tests construct invalid states intentionally.

  • any other value (scalar / AR record) → ‘[normalize_one(value), nil]`. BC path for `with_scope(scalar)`: single-arg block usage continues to mean “scope=scalar, parent_scope=nil”.



54
55
56
57
58
59
 
# File 'lib/typed_eav/scope_tuple.rb', line 54

def normalize_permissive(value)
  return nil if value.nil?
  return [normalize_one(value[0]), normalize_one(value[1])] if value.is_a?(Array) && value.size == 2

  [normalize_one(value), nil]
end

.normalize_strict(value) ⇒ Object

Strict-contract normalizer for ‘Config.scope_resolver` return values. Accepts ONLY `nil` or a 2-element Array. Bare scalars, 1-element Arrays, and 3-element Arrays raise `ArgumentError` quoting the bad input and pointing at the migration note — this is the chokepoint that makes a v0.1.x bare-scalar resolver fail loudly under Phase 1.



66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/typed_eav/scope_tuple.rb', line 66

def normalize_strict(value)
  return nil if value.nil?

  unless value.is_a?(Array) && value.size == 2
    raise ArgumentError,
          "TypedEAV.config.scope_resolver must return a 2-element " \
          "[scope, parent_scope] Array (or nil). Got: #{value.inspect}. " \
          "v0.1.x resolvers returning a bare scalar must be updated — " \
          "see CHANGELOG and the README migration note."
  end

  [normalize_one(value[0]), normalize_one(value[1])]
end