cake

-module(cake@join).
-compile([no_auto_import, nowarn_unused_vars, nowarn_unused_function, nowarn_nomatch]).
-define(FILEPATH, "src/cake/join.gleam").
-export([table/1, sub_query/1, inner/3, left/3, right/3, full/3, cross/2, inner_lateral/2, left_lateral/2, cross_lateral/2]).

-if(?OTP_RELEASE >= 27).
-define(MODULEDOC(Str), -moduledoc(Str)).
-define(DOC(Str), -doc(Str)).
-else.
-define(MODULEDOC(Str), -compile([])).
-define(DOC(Str), -compile([])).
-endif.

?MODULEDOC(
    " Functions to build `JOIN` clauses of SQL queries.\n"
    "\n"
    " Tables, views and sub-queries can be joined together.\n"
    "\n"
    " ## Supported join kinds\n"
    "\n"
    " - `INNER JOIN`\n"
    " - `LEFT JOIN`, inclusive, same as `LEFT OUTER JOIN`,\n"
    " - `RIGHT JOIN`, inclusive, same as `RIGHT OUTER JOIN`,\n"
    " - `FULL JOIN`, inclusive, same as `FULL OUTER JOIN`,\n"
    " - `CROSS JOIN`\n"
    "\n"
    " You can also build following joins using the provided query builder\n"
    " functions:\n"
    "\n"
    " - `SELF JOIN`: Use the same table, view, or sub-query with a different\n"
    "    alias.\n"
    " - `EXCLUSIVE LEFT JOIN`: `WHERE b.key IS NULL`\n"
    " - `EXCLUSIVE RIGHT JOIN`: `WHERE a.key IS NULL`\n"
    " - `EXCLUSIVE FULL JOIN`: `WHERE a.key IS NULL OR b.key IS NULL`\n"
    "\n"
).

-file("src/cake/join.gleam", 46).
?DOC(" Create a `JOIN` target from a table name.\n").
-spec table(binary()) -> cake@internal@read_query:join_target().
table(Tbl_nm) ->
    _pipe = Tbl_nm,
    {join_table, _pipe}.

-file("src/cake/join.gleam", 52).
?DOC(" Create a `JOIN` target from a sub-query.\n").
-spec sub_query(cake@internal@read_query:read_query()) -> cake@internal@read_query:join_target().
sub_query(Sq) ->
    _pipe = Sq,
    {join_sub_query, _pipe}.

-file("src/cake/join.gleam", 58).
?DOC(" Create an `INNER JOIN`.\n").
-spec inner(
    cake@internal@read_query:join_target(),
    cake@internal@read_query:where(),
    binary()
) -> cake@internal@read_query:join().
inner(Wth, On, Als) ->
    _pipe = Wth,
    {inner_join, _pipe, Als, On}.

-file("src/cake/join.gleam", 70).
?DOC(
    " Creates a `LEFT JOIN`.\n"
    "\n"
    " Also called `LEFT OUTER JOIN`.\n"
    "\n"
    " _Inclusive_ by default.\n"
    "\n"
    " Set `on` to `WHERE a.key IS NULL` to make it _exclusive_.\n"
).
-spec left(
    cake@internal@read_query:join_target(),
    cake@internal@read_query:where(),
    binary()
) -> cake@internal@read_query:join().
left(Wth, On, Als) ->
    _pipe = Wth,
    {left_join, _pipe, Als, On}.

-file("src/cake/join.gleam", 82).
?DOC(
    " Creates a `RIGHT JOIN`.\n"
    "\n"
    " Also called `RIGHT OUTER JOIN`.\n"
    "\n"
    " _Inclusive_ by default.\n"
    "\n"
    " Set `on` to `WHERE b.key IS NULL` to make it _exclusive_.\n"
).
-spec right(
    cake@internal@read_query:join_target(),
    cake@internal@read_query:where(),
    binary()
) -> cake@internal@read_query:join().
right(Wth, On, Als) ->
    _pipe = Wth,
    {right_join, _pipe, Als, On}.

-file("src/cake/join.gleam", 94).
?DOC(
    " Creates a `FULL JOIN`.\n"
    "\n"
    " Also called `FULL OUTER JOIN`.\n"
    "\n"
    " _Inclusive_ by default.\n"
    "\n"
    " Set `on` to `WHERE a.key IS NULL OR b.key IS NULL` to make it _exclusive_.\n"
).
-spec full(
    cake@internal@read_query:join_target(),
    cake@internal@read_query:where(),
    binary()
) -> cake@internal@read_query:join().
full(Wth, On, Als) ->
    _pipe = Wth,
    {full_join, _pipe, Als, On}.

-file("src/cake/join.gleam", 102).
?DOC(
    " Creates a `CROSS JOIN`.\n"
    "\n"
    " Also called _cartesian product_.\n"
).
-spec cross(cake@internal@read_query:join_target(), binary()) -> cake@internal@read_query:join().
cross(Wth, Als) ->
    _pipe = Wth,
    {cross_join, _pipe, Als}.

-file("src/cake/join.gleam", 125).
?DOC(
    " Creates a `INNER JOIN LATERAL ... ON TRUE`.\n"
    "\n"
    " ⚠️⚠️⚠️\n"
    "\n"
    " CAUTION: `LATERAL` joins are not optimized by the query planner,\n"
    " and can be very slow on large datasets, especially when the sub-query\n"
    " returns many rows.\n"
    "\n"
    " ⚠️⚠️⚠️\n"
    "\n"
    " See <https://www.postgresql.org/docs/9.3/sql-select.html#SQL-FROM> for an\n"
    " explanation on how `LATERAL` works.\n"
    "\n"
    " Any filtering must be done in WHERE clauses as the JOIN ON clause is always\n"
    " TRUE when calling this function.\n"
    "\n"
    " NOTICE: `LATERAL` is supported by 🐘PostgreSQL 9.3+ and recent 🐬MySQL\n"
    " versions.\n"
).
-spec inner_lateral(cake@internal@read_query:join_target(), binary()) -> cake@internal@read_query:join().
inner_lateral(Wth, Als) ->
    _pipe = Wth,
    {inner_join_lateral_on_true, _pipe, Als}.

-file("src/cake/join.gleam", 148).
?DOC(
    " Creates a `LEFT JOIN LATERAL ... ON TRUE`.\n"
    "\n"
    " ⚠️⚠️⚠️\n"
    "\n"
    " CAUTION: `LATERAL` joins are not optimized by the query planner,\n"
    " and can be very slow on large datasets, especially when the sub-query\n"
    " returns many rows.\n"
    "\n"
    " ⚠️⚠️⚠️\n"
    "\n"
    " See <https://www.postgresql.org/docs/9.3/sql-select.html#SQL-FROM> for an\n"
    " explanation on how `LATERAL` works.\n"
    "\n"
    " Any filtering must be done in WHERE clauses as the JOIN ON clause is always\n"
    " TRUE when calling this function.\n"
    "\n"
    " NOTICE: `LATERAL` is supported by 🐘PostgreSQL 9.3+ and recent 🐬MySQL\n"
    " versions.\n"
).
-spec left_lateral(cake@internal@read_query:join_target(), binary()) -> cake@internal@read_query:join().
left_lateral(Wth, Als) ->
    _pipe = Wth,
    {left_join_lateral_on_true, _pipe, Als}.

-file("src/cake/join.gleam", 168).
?DOC(
    " Creates a `CROSS JOIN LATERAL`.\n"
    "\n"
    " ⚠️⚠️⚠️\n"
    "\n"
    " CAUTION: `LATERAL` joins are not optimized by the query planner,\n"
    " and can be very slow on large datasets, especially when the sub-query\n"
    " returns many rows.\n"
    "\n"
    " ⚠️⚠️⚠️\n"
    "\n"
    " See <https://www.postgresql.org/docs/9.3/sql-select.html#SQL-FROM> for an\n"
    " explanation on how `LATERAL` works.\n"
    "\n"
    " NOTICE: `LATERAL` is supported by 🐘PostgreSQL 9.3+ and recent 🐬MySQL\n"
    " versions.\n"
).
-spec cross_lateral(cake@internal@read_query:join_target(), binary()) -> cake@internal@read_query:join().
cross_lateral(Wth, Als) ->
    _pipe = Wth,
    {cross_join_lateral, _pipe, Als}.