@type advanced_join_type() ::
  :hierarchical | :tagging | :dimension | :star_dimension | :snowflake_dimension

@type association() :: %{
  :queryable => atom(),
  :field => atom(),
  :owner_key => atom(),
  :related_key => atom(),
  optional(:cardinality) => :one | :many,
  optional(:through) => [atom()]
}

@type atom_or_string() :: atom() | String.t()

@type basic_filter() :: {field_name(), term()}

@type basic_join_config() :: %{
  :type => basic_join_type(),
  optional(:name) => String.t(),
  optional(:on) => term(),
  optional(:joins) => %{required(atom()) => join_config()}
}

@type basic_join_type() :: :left | :right | :inner | :full

@type basic_selector() :: field_name()

@type builder_result() :: {iodata_with_markers(), sql_params(), join_dependencies()}

@type case_selector() ::
  {:case, conditions :: [{condition :: term(), value :: term()}],
   else_value :: term()}

@type column_definition() :: %{
  :type => column_type(),
  optional(:icon) => atom() | String.t(),
  optional(:icon_family) => atom() | String.t(),
  optional(:presentation_type) =>
    :date | :datetime | :utc_datetime | :naive_datetime,
  optional(:presentation) => %{
    optional(:semantic_type) => :measurement | :temporal | :number,
    optional(:quantity) => atom() | String.t(),
    optional(:canonical_unit) => atom() | String.t(),
    optional(:available_units) => [atom() | String.t()],
    optional(:default_unit) => atom() | String.t(),
    optional(:temporal_kind) =>
      :instant | :local_date | :local_time | :naive_datetime,
    optional(:storage_timezone) => String.t(),
    optional(:display_timezone) => :viewer | String.t(),
    optional(:format) => map()
  },
  optional(:datetime_storage) =>
    :unix
    | :unix_s
    | :unix_seconds
    | :unix_ms
    | :unix_milliseconds
    | :javascript_ms,
  optional(:precision) => pos_integer(),
  optional(:scale) => non_neg_integer(),
  optional(:default) => term(),
  optional(:null) => boolean()
}

@type column_type() ::
  :integer
  | :string
  | :text
  | :boolean
  | :decimal
  | :float
  | :date
  | :time
  | :utc_datetime
  | :naive_datetime
  | :binary
  | :uuid
  | :json
  | :jsonb
  | :array
  | :geometry
  | :geography
  | :point
  | :linestring
  | :polygon
  | :multipoint
  | :multilinestring
  | :multipolygon
  | :geometrycollection

@type comparison_filter() :: {field_name(), {comparison_operator(), term()}}

@type comparison_operator() ::
  :eq
  | :not_eq
  | :gt
  | :gte
  | :lt
  | :lte
  | :like
  | :ilike
  | :not_like
  | :not_ilike
  | :is_null
  | :not_null
  | :in
  | :not_in
  | :between
  | :not_between

@type configure_options() :: [
  validate: boolean(),
  pool: boolean(),
  pool_options: keyword(),
  adapter: module(),
  rollup_sort_fix: boolean() | :auto
]

@type cte_builder_result() ::
  {iodata_with_markers(), sql_params(), [cte_definition()]}

@type cte_definition() :: %{
  name: String.t(),
  sql: iodata_with_markers(),
  params: sql_params(),
  recursive: boolean()
}

@type cte_marker() :: {:cte, name :: String.t(), iodata_fragment()}

@type custom_selector() :: {:custom, sql :: String.t(), params :: [term()]}

@type detail_action() :: %{
  :name => String.t(),
  :type => detail_action_type(),
  optional(:description) => String.t(),
  optional(:required_fields) => [field_name()],
  optional(:payload) => map()
}

@type detail_action_type() ::
  :modal | :iframe_modal | :external_link | :live_component

@type dimension_join_config() :: %{
  :type => :dimension | :star_dimension | :snowflake_dimension,
  :display_field => atom(),
  optional(:dimension_key) => atom(),
  optional(:normalization_joins) => [
    %{table: String.t(), key: atom(), foreign_key: atom()}
  ],
  optional(:joins) => %{required(atom()) => join_config()}
}

@type domain() :: %{
  :name => String.t(),
  :source => source(),
  :schemas => %{required(atom()) => schema()},
  :joins => %{required(atom()) => join_config()},
  optional(:default_selected) => [selector()],
  optional(:required_filters) => [filter()],
  optional(:required_selected) => [selector()],
  optional(:required_order_by) => [order_spec()],
  optional(:required_group_by) => [field_name()],
  optional(:filters) => %{required(String.t()) => term()},
  optional(:detail_actions) => %{
    optional(atom() | String.t()) => detail_action()
  },
  optional(:domain_data) => term(),
  optional(:extensions) => [term()],
  optional(:functions) => function_registry(),
  optional(:query_members) => query_member_registry(),
  optional(:published_views) => published_view_registry()
}

@type domain_option_provider() :: %{
  type: :domain,
  domain: atom(),
  value_field: atom(),
  display_field: atom(),
  filters: [filter()],
  order_by: [order_spec()]
}

@type enum_option_provider() :: %{type: :enum, schema: module(), field: atom()}

@type execute_one_result_error() :: {:error, Selecto.Error.t()}

@type execute_one_result_ok() :: {:ok, single_row_result()}

@type execute_options() :: [
  timeout: timeout(),
  log: boolean(),
  max_rows: pos_integer(),
  receive_timeout: timeout(),
  queue_timeout: timeout(),
  stream_timeout: timeout(),
  analyze_complexity: boolean(),
  format: term(),
  format_options: keyword() | map(),
  cache: boolean(),
  cache_ttl: pos_integer(),
  cache_namespace: String.t(),
  stream_producer: function()
]

@type execute_result_error() :: {:error, Selecto.Error.t()}

@type execute_result_ok() :: {:ok, query_result()}

@type execute_stream_result_error() :: {:error, Selecto.Error.t()}

@type execute_stream_result_ok() :: {:ok, Enumerable.t()}

@type extract_selector() :: {:extract, part :: String.t(), from_field :: field_name()}

@type field_name() :: atom() | String.t()

@type filter() :: basic_filter() | comparison_filter() | logical_filter()

@type function_arg_spec() :: %{
  name: atom() | String.t(),
  type: term(),
  source: :selector | :value | :literal
}

@type function_kind() :: :scalar | :predicate | :table

@type function_registry() :: %{optional(atom() | String.t()) => function_spec()}

@type function_selector() ::
  {:func, function_name :: String.t(), args :: [field_name() | term()]}

@type function_spec() :: %{
  :kind => function_kind(),
  :sql_name => String.t(),
  optional(:args) => [function_arg_spec()],
  optional(:returns) => term(),
  optional(:allowed_in) => [atom()]
}

@type hierarchical_join_config() :: %{
  :type => :hierarchical,
  :hierarchy_type => hierarchy_type(),
  optional(:depth_limit) => pos_integer(),
  optional(:path_field) => atom(),
  optional(:path_separator) => String.t(),
  optional(:root_condition) => term(),
  optional(:joins) => %{required(atom()) => join_config()}
}

@type hierarchy_type() :: :adjacency_list | :materialized_path | :closure_table

@type iodata_fragment() :: iolist() | String.t()

@type iodata_with_markers() :: [iodata_fragment() | param_marker() | cte_marker()]

@type join_config() ::
  basic_join_config()
  | hierarchical_join_config()
  | tagging_join_config()
  | dimension_join_config()

@type join_dependencies() :: [join_requirement()]

@type join_requirement() :: {join_name :: atom(), required_for :: String.t()}

@type join_type() :: basic_join_type() | advanced_join_type()

@type logical_filter() :: {:and | :or, [filter()]}

@type maybe(t) :: {:ok, t} | {:error, term()}

@type option_provider() ::
  static_option_provider()
  | domain_option_provider()
  | enum_option_provider()
  | query_option_provider()

@type order_direction() :: :asc | :desc

@type order_spec() :: field_name() | {order_direction(), field_name()}

@type param_marker() :: {:param, term()}

@type pivot_config() :: retarget_config()

@type pivot_join_path() :: retarget_join_path()

@type processed_config() :: %{
  :source => source(),
  :source_table => table_name(),
  :primary_key => atom(),
  :columns => %{required(String.t()) => %{name: String.t()}},
  :joins => %{required(atom()) => processed_join()},
  :filters => %{required(String.t()) => term()},
  optional(:functions) => function_registry(),
  :domain_data => term(),
  optional(:extensions) => [{module(), keyword()}]
}

@type processed_join() :: %{
  :type => join_type(),
  :source => atom() | String.t(),
  :name => String.t(),
  optional(:fields) => %{required(String.t()) => %{name: String.t()}},
  optional(:filters) => %{required(String.t()) => term()},
  optional(:joins) => %{required(atom()) => processed_join()},
  optional(:parameters) => [term()],
  optional(:hierarchy_type) => hierarchy_type(),
  optional(:depth_limit) => pos_integer(),
  optional(:path_field) => atom(),
  optional(:path_separator) => String.t(),
  optional(:tag_field) => atom(),
  optional(:weight_field) => atom(),
  optional(:display_field) => atom(),
  optional(:dimension_key) => atom()
}

@type published_view_kind() :: :view | :materialized_view

@type published_view_registry() :: %{
  optional(atom() | String.t()) => published_view_spec()
}

@type published_view_spec() :: %{
  :database_name => String.t(),
  :kind => published_view_kind(),
  :query => function(),
  :columns => %{optional(atom() | String.t()) => map()},
  optional(:indexes) => [map()],
  optional(:refresh) => map()
}

@type query_member_registry() :: %{
  optional(:ctes) => %{optional(atom() | String.t()) => map()},
  optional(:values) => %{optional(atom() | String.t()) => map()},
  optional(:subqueries) => %{optional(atom() | String.t()) => map()},
  optional(:laterals) => %{optional(atom() | String.t()) => map()},
  optional(:unnests) => %{optional(atom() | String.t()) => map()}
}

@type query_option_provider() :: %{type: :query, query: String.t(), params: [term()]}

@type query_result() ::
  {rows :: [[term()]], columns :: [String.t()],
   aliases :: %{required(String.t()) => String.t()}}

@type query_set() :: %{
  :selected => [selector()],
  :filtered => [filter()],
  optional(:required_filters) => [filter()],
  optional(:post_retarget_filters) => [filter()],
  optional(:post_pivot_filters) => [filter()],
  :order_by => [order_spec()],
  :group_by => [field_name()],
  optional(:retarget_state) => retarget_config(),
  optional(:pivot_state) => retarget_config(),
  optional(:subselected) => [subselect_selector()]
}

@type relation_source_kind() :: :table | :view | :materialized_view

@type result(t, e) :: {:ok, t} | {:error, e}

@type retarget_config() :: %{
  :target_schema => atom(),
  :join_path => [atom()],
  optional(:preserve_filters) => boolean(),
  optional(:subquery_strategy) => :exists | :in | :join
}

@type retarget_join_path() :: [
  %{
    from_schema: atom(),
    to_schema: atom(),
    association_name: atom(),
    join_type: join_type()
  }
]

@type safe_execute_one_result() ::
  execute_one_result_ok() | execute_one_result_error()

@type safe_execute_result() :: execute_result_ok() | execute_result_error()

@type safe_execute_stream_result() ::
  execute_stream_result_ok() | execute_stream_result_error()

@type schema() :: %{
  :name => String.t(),
  :source_table => table_name(),
  :primary_key => atom(),
  :fields => [atom()],
  :redact_fields => [atom()],
  :columns => %{required(atom()) => column_definition()},
  :associations => %{required(atom()) => association()},
  optional(:source_kind) => relation_source_kind(),
  optional(:readonly) => boolean(),
  optional(:custom_filters) => %{required(atom()) => term()}
}

@type select_options_column() :: %{
  :type => :select_options,
  :option_provider => option_provider(),
  :name => String.t(),
  optional(:multiple) => boolean(),
  optional(:searchable) => boolean(),
  optional(:cache_ttl) => pos_integer()
}

@type selector() ::
  basic_selector()
  | function_selector()
  | case_selector()
  | extract_selector()
  | window_selector()
  | custom_selector()

@type single_row_result() ::
  {row :: [term()], aliases :: %{required(String.t()) => String.t()}}

@type source() :: %{
  :source_table => table_name(),
  :primary_key => atom(),
  :fields => [atom()],
  :redact_fields => [atom()],
  :columns => %{required(atom()) => column_definition()},
  :associations => %{required(atom()) => association()},
  optional(:source_kind) => relation_source_kind(),
  optional(:readonly) => boolean()
}

@type sql_error() :: term()

@type sql_generation_options() :: [
  include_comments: boolean(),
  pretty_print: boolean()
]

@type sql_params() :: [term()]

@type sql_result() :: {sql :: String.t(), params :: sql_params()}

@type static_option_provider() :: %{type: :static, values: [term()]}

@type stream_row_result() ::
  {row :: [term()], columns :: [String.t()], aliases :: [String.t()]}

@type subselect_config() :: %{
  :target_table => table_name(),
  :join_condition => {field_name(), field_name()},
  :aggregation_type => subselect_format(),
  optional(:additional_filters) => [filter()]
}

@type subselect_format() :: :json_agg | :array_agg | :string_agg | :count

@type subselect_selector() :: %{
  :fields => [field_name()],
  :target_schema => atom(),
  :format => subselect_format(),
  optional(:alias) => String.t(),
  optional(:join_path) => [atom() | String.t()],
  optional(:separator) => String.t(),
  optional(:order_by) => [order_spec()],
  optional(:filters) => [filter()]
}

@type t() :: %Selecto{
  adapter: module() | nil,
  config: processed_config(),
  connection: term() | nil,
  domain: domain(),
  extensions: [{module(), keyword()}],
  postgrex_opts: term() | nil,
  set: query_set(),
  tenant: tenant_context() | nil
}

@type table_name() :: String.t()

@type tagging_join_config() :: %{
  :type => :tagging,
  :tag_field => atom(),
  optional(:weight_field) => atom(),
  optional(:min_weight) => number(),
  optional(:aggregation) => :string_agg | :array_agg | :count,
  optional(:separator) => String.t(),
  optional(:joins) => %{required(atom()) => join_config()}
}

@type tenant_context() :: %{
  optional(:tenant_id) => term(),
  optional(:tenant_mode) => atom() | String.t(),
  optional(:tenant_field) => atom() | String.t(),
  optional(:prefix) => String.t(),
  optional(:namespace) => String.t(),
  optional(:required_filters) => [filter()]
}

@type window_selector() ::
  {:window, function_name :: String.t(), args :: [term()],
   window_spec :: term()}