Diffo.Provider.Place (Diffo v0.5.0)

Copy Markdown View Source

Abstract Place reader — plumbing, not a TMF subtype recommendation.

TMF675 treats Place as abstract; the concrete subtypes are Diffo.Provider.GeographicAddress, Diffo.Provider.GeographicSite, and Diffo.Provider.GeographicLocation. Use those (or your own domain leaf composed from BasePlace + the matching BaseGeographic* fragment) for any new Place data.

This resource is kept in core minimally to serve two roles:

  1. Abstract reader for projection bootstrap. Diffo.Provider.get_place_by_id!/1 and friends load via this resource so AshNeo4j.worlds/1 can project the loaded node to its outermost concrete world. Symmetric with how Diffo.Provider.Instance (the abstract reader for Instance) backs Diffo.Provider.Calculations.InheritedCharacteristic projection.
  2. PlaceRef-typed placeholder. A Place record with type: :PlaceRef and referred_type: set represents a reference to an externally-managed Place. Diffo.Provider.create_place!(:PlaceRef, %{referred_type: :X, ...}) routes to this resource's :create action.

See Diffo.Provider.BasePlace for the underlying fragment, attributes, validations, and TMF675 GeoJson wire encoding.

Preferred API

Production code should use the typed subtype leaves (GeographicAddress / GeographicSite / GeographicLocation) or, more ergonomically, the type-atom dispatcher on Diffo.Provider:

Diffo.Provider.create_place!(:GeographicSite, %{...})

Reads go through the dispatcher's projection path:

Diffo.Provider.get_place_by_id!(id)    # returns concrete subtype struct

An Ash Resource for a TMF Place

Summary

Types

t()

Functions

default_short_name()
input(opts)

Validates that the keys in the provided input are valid for at least one action on the resource.

input(opts, action)

Same as input/1, except restricts the keys to values accepted by the action provided.

primary_key_matches?(left, right)

Types

t()

@type t() :: %Diffo.Provider.Place{
  __lateral_join_source__: term(),
  __meta__: term(),
  __metadata__: term(),
  __order__: term(),
  aggregates: term(),
  bounds: term(),
  calculations: term(),
  created_at: term(),
  href: term(),
  id: term(),
  location: term(),
  name: term(),
  place_refs: term(),
  referred_type: term(),
  type: term(),
  updated_at: term()
}

Functions

default_short_name()

input(opts)

@spec input(values :: map() | Keyword.t()) :: map() | no_return()

Validates that the keys in the provided input are valid for at least one action on the resource.

Raises a KeyError error at compile time if not. This exists because generally a struct should only ever be created by Ash as a result of a successful action. You should not be creating records manually in code, e.g %MyResource{value: 1, value: 2}. Generally that is fine, but often with embedded resources it is nice to be able to validate the keys that are being provided, e.g

Resource
|> Ash.Changeset.for_create(:create, %{embedded: EmbeddedResource.input(foo: 1, bar: 2)})
|> Ash.create()

input(opts, action)

@spec input(values :: map() | Keyword.t(), action :: atom()) :: map() | no_return()

Same as input/1, except restricts the keys to values accepted by the action provided.

primary_key_matches?(left, right)