/*
 * Copyright 2015-2022 Transmogrify LLC, 2022-2026 Revetware LLC.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.pyranid;

import com.pyranid.JsonParameter.BindingPreference;
import org.jspecify.annotations.NonNull;
import org.jspecify.annotations.Nullable;

import javax.annotation.concurrent.ThreadSafe;
import java.lang.reflect.Array;
import java.lang.reflect.Type;
import java.math.BigDecimal;
import java.util.Collection;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.Set;

import static java.util.Objects.requireNonNull;

/**
 * Fluent interface for acquiring instances of specialized parameter types.
 *
 * @author <a href="https://www.revetkn.com">Mark Allen</a>
 * @since 3.0.0
 */
@ThreadSafe
public final class Parameters {
        private Parameters() {
                // Prevents instantiation
        }

        /**
         * Acquires a SQL ARRAY parameter for a {@link List} given an appropriate <a href="https://docs.oracle.com/en/java/javase/24/docs/api/java.sql/java/sql/Array.html#getBaseTypeName()" target="_blank">{@code java.sql.Array#getBaseTypeName()}</a>.
         * <p>
         * You may determine available {@code baseTypeName} values for your database by examining metadata exposed via {@link Database#readDatabaseMetaData(DatabaseMetaDataReader)}.
         * <p>
         * For non-SQL array binding where you need to preserve the Java element type for custom binders,
         * use {@link #arrayOf(Class, Object)} instead.
         *
         * @param baseTypeName the SQL ARRAY element type, e.g. {@code "text"}, {@code "uuid"}, {@code "float4"}, {@code "float8"} ...
         * @param list         the list whose elements will be used to populate the SQL ARRAY
         * @param <E>          the element type of the Java list ({@code List<E>}); each element must be bindable to {@code baseTypeName} by the active {@link PreparedStatementBinder}.
         * @return a SQL ARRAY parameter for the given list
         */
        @NonNull
        public static <E> SqlArrayParameter<E> sqlArrayOf(@NonNull String baseTypeName,
                                                                                                                                                                                                                @Nullable List<E> list) {
                requireNonNull(baseTypeName);
                return new DefaultSqlArrayParameter(baseTypeName, list == null ? null : list.toArray());
        }

        /**
         * Acquires a SQL ARRAY parameter for a native Java array given an appropriate <a href="https://docs.oracle.com/en/java/javase/24/docs/api/java.sql/java/sql/Array.html#getBaseTypeName()" target="_blank">{@code java.sql.Array#getBaseTypeName()}</a>.
         * <p>
         * You may determine available {@code baseTypeName} values for your database by examining metadata exposed via {@link Database#readDatabaseMetaData(DatabaseMetaDataReader)}.
         * <p>
         * For non-SQL array binding where you need to preserve the Java element type for custom binders,
         * use {@link #arrayOf(Class, Object)} instead.
         *
         * @param baseTypeName the SQL ARRAY element type, e.g. {@code "text"}, {@code "uuid"}, {@code "float4"}, {@code "float8"} ...
         * @param array        the native Java array whose elements will be used to populate the SQL ARRAY
         * @param <E>          the element type of the Java array ({@code T[]}); each element must be bindable to {@code baseTypeName} by the active {@link PreparedStatementBinder}.
         * @return a SQL ARRAY parameter for the given Java array
         */
        @NonNull
        public static <E> SqlArrayParameter<E> sqlArrayOf(@NonNull String baseTypeName,
                                                                                                                                                                                                                E @Nullable [] array) {
                requireNonNull(baseTypeName);
                return new DefaultSqlArrayParameter(baseTypeName, array);
        }

        /**
         * Default package-private implementation of {@link SqlArrayParameter}.
         *
         * @author <a href="https://www.revetkn.com">Mark Allen</a>
         * @since 3.0.0
         */
        @ThreadSafe
        static class DefaultSqlArrayParameter implements SqlArrayParameter {
                @NonNull
                private final String baseTypeName; // e.g. "text", "uuid", "integer", ...
                @Nullable
                private final Object @Nullable [] elements;

                DefaultSqlArrayParameter(@NonNull String baseTypeName,
                                                                                                                 Object @Nullable [] elements) {
                        requireNonNull(baseTypeName);

                        this.baseTypeName = baseTypeName;
                        this.elements = elements == null ? null : elements.clone(); // Always perform a defensive copy
                }

                /**
                 * Gets the element type of this SQL ARRAY, which corresponds to the value of <a href="https://docs.oracle.com/en/java/javase/24/docs/api/java.sql/java/sql/Array.html#getBaseTypeName()" target="_blank">{@code java.sql.Array#getBaseTypeName()}</a>
                 * and is database-specific.
                 *
                 * @return the element type of this SQL ARRAY
                 */
                @NonNull
                @Override
                public String getBaseTypeName() {
                        return this.baseTypeName;
                }

                /**
                 * Gets the elements of this SQL ARRAY.
                 *
                 * @return the elements of this SQL ARRAY
                 */
                @NonNull
                @Override
                public Optional<Object[]> getElements() {
                        // Defensive copy
                        return this.elements == null ? Optional.empty() : Optional.of(this.elements.clone());
                }
        }

        /**
         * Acquires a parameter for SQL {@code IN} list expansion using a {@link Collection}.
         * Elements must be non-empty.
         *
         * @param elements the elements to expand into SQL {@code IN} list placeholders
         * @param <E>      the element type
         * @return an IN-list parameter for the given elements
         */
        @NonNull
        public static <E> InListParameter inList(@NonNull Collection<@Nullable E> elements) {
                requireNonNull(elements);
                return new DefaultInListParameter(elements.toArray());
        }

        /**
         * Acquires a parameter for SQL {@code IN} list expansion using a Java array.
         * Elements must be non-empty.
         *
         * @param elements the elements to expand into SQL {@code IN} list placeholders
         * @param <E>      the element type
         * @return an IN-list parameter for the given elements
         */
        @NonNull
        public static <E> InListParameter inList(@NonNull E @Nullable [] elements) {
                requireNonNull(elements);
                return new DefaultInListParameter(elements);
        }

        /**
         * Acquires a parameter for SQL {@code IN} list expansion using a {@code byte[]} array.
         * Elements must be non-empty.
         *
         * @param elements the elements to expand into SQL {@code IN} list placeholders
         * @return an IN-list parameter for the given elements
         */
        @NonNull
        public static InListParameter inList(byte @NonNull [] elements) {
                requireNonNull(elements);
                Object[] boxed = new Object[elements.length];
                for (int i = 0; i < elements.length; i++)
                        boxed[i] = elements[i];
                return new DefaultInListParameter(boxed);
        }

        /**
         * Acquires a parameter for SQL {@code IN} list expansion using a {@code short[]} array.
         * Elements must be non-empty.
         *
         * @param elements the elements to expand into SQL {@code IN} list placeholders
         * @return an IN-list parameter for the given elements
         */
        @NonNull
        public static InListParameter inList(short @NonNull [] elements) {
                requireNonNull(elements);
                Object[] boxed = new Object[elements.length];
                for (int i = 0; i < elements.length; i++)
                        boxed[i] = elements[i];
                return new DefaultInListParameter(boxed);
        }

        /**
         * Acquires a parameter for SQL {@code IN} list expansion using an {@code int[]} array.
         * Elements must be non-empty.
         *
         * @param elements the elements to expand into SQL {@code IN} list placeholders
         * @return an IN-list parameter for the given elements
         */
        @NonNull
        public static InListParameter inList(int @NonNull [] elements) {
                requireNonNull(elements);
                Object[] boxed = new Object[elements.length];
                for (int i = 0; i < elements.length; i++)
                        boxed[i] = elements[i];
                return new DefaultInListParameter(boxed);
        }

        /**
         * Acquires a parameter for SQL {@code IN} list expansion using a {@code long[]} array.
         * Elements must be non-empty.
         *
         * @param elements the elements to expand into SQL {@code IN} list placeholders
         * @return an IN-list parameter for the given elements
         */
        @NonNull
        public static InListParameter inList(long @NonNull [] elements) {
                requireNonNull(elements);
                Object[] boxed = new Object[elements.length];
                for (int i = 0; i < elements.length; i++)
                        boxed[i] = elements[i];
                return new DefaultInListParameter(boxed);
        }

        /**
         * Acquires a parameter for SQL {@code IN} list expansion using a {@code float[]} array.
         * Elements must be non-empty.
         *
         * @param elements the elements to expand into SQL {@code IN} list placeholders
         * @return an IN-list parameter for the given elements
         */
        @NonNull
        public static InListParameter inList(float @NonNull [] elements) {
                requireNonNull(elements);
                Object[] boxed = new Object[elements.length];
                for (int i = 0; i < elements.length; i++)
                        boxed[i] = elements[i];
                return new DefaultInListParameter(boxed);
        }

        /**
         * Acquires a parameter for SQL {@code IN} list expansion using a {@code double[]} array.
         * Elements must be non-empty.
         *
         * @param elements the elements to expand into SQL {@code IN} list placeholders
         * @return an IN-list parameter for the given elements
         */
        @NonNull
        public static InListParameter inList(double @NonNull [] elements) {
                requireNonNull(elements);
                Object[] boxed = new Object[elements.length];
                for (int i = 0; i < elements.length; i++)
                        boxed[i] = elements[i];
                return new DefaultInListParameter(boxed);
        }

        /**
         * Acquires a parameter for SQL {@code IN} list expansion using a {@code boolean[]} array.
         * Elements must be non-empty.
         *
         * @param elements the elements to expand into SQL {@code IN} list placeholders
         * @return an IN-list parameter for the given elements
         */
        @NonNull
        public static InListParameter inList(boolean @NonNull [] elements) {
                requireNonNull(elements);
                Object[] boxed = new Object[elements.length];
                for (int i = 0; i < elements.length; i++)
                        boxed[i] = elements[i];
                return new DefaultInListParameter(boxed);
        }

        /**
         * Acquires a parameter for SQL {@code IN} list expansion using a {@code char[]} array.
         * Elements must be non-empty.
         *
         * @param elements the elements to expand into SQL {@code IN} list placeholders
         * @return an IN-list parameter for the given elements
         */
        @NonNull
        public static InListParameter inList(char @NonNull [] elements) {
                requireNonNull(elements);
                Object[] boxed = new Object[elements.length];
                for (int i = 0; i < elements.length; i++)
                        boxed[i] = elements[i];
                return new DefaultInListParameter(boxed);
        }

        /**
         * Default package-private implementation of {@link InListParameter}.
         *
         * @author <a href="https://www.revetkn.com">Mark Allen</a>
         * @since 4.0.0
         */
        @ThreadSafe
        static class DefaultInListParameter implements InListParameter {
                @NonNull
                private final Object[] elements;

                DefaultInListParameter(Object @NonNull [] elements) {
                        requireNonNull(elements);
                        this.elements = elements.clone(); // Always perform a defensive copy
                }

                @NonNull
                @Override
                public Object @NonNull [] getElements() {
                        // Defensive copy
                        return this.elements.clone();
                }
        }

        /**
         * Acquires a parameter of array type, preserving element type information so it is accessible at runtime.
         * <p>
         * This is useful when you want to bind an array via a {@link CustomParameterBinder} and need the
         * component type to be preserved for {@link TargetType} matching.
         * <p>
         * For SQL {@code ARRAY} binding, use {@link #sqlArrayOf(String, Object[])} instead.
         * If you need a formal SQL {@code ARRAY} parameter for JDBC array binding, do not use this method.
         * <p>
         * <strong>Note:</strong> this kind of parameter requires a corresponding {@link CustomParameterBinder}
         * to be registered, even when the wrapped value is {@code null}; implement {@link CustomParameterBinder#bindNull}
         * if you want typed nulls to bind successfully.
         *
         * @param elementType the element type of the array
         * @param array       the array value to wrap; may be {@code null}
         * @param <E>         the element type of the array
         * @return a {@link TypedParameter} representing a {@code E[]} suitable for use with custom binders
         */
        @NonNull
        public static <E> TypedParameter arrayOf(@NonNull Class<E> elementType,
                                                                                                                                                                         E @Nullable [] array) {
                requireNonNull(elementType);
                return arrayOf((Class<?>) elementType, array);
        }

        /**
         * Acquires a parameter of array type, preserving element type information so it is accessible at runtime.
         * <p>
         * This overload supports primitive arrays by passing the primitive component class
         * (for example, {@code int.class}) and the corresponding primitive array.
         * <p>
         * For SQL {@code ARRAY} binding, use {@link #sqlArrayOf(String, Object[])} instead.
         * If you need a formal SQL {@code ARRAY} parameter for JDBC array binding, do not use this method.
         * <p>
         * <strong>Note:</strong> this kind of parameter requires a corresponding {@link CustomParameterBinder}
         * to be registered, even when the wrapped value is {@code null}; implement {@link CustomParameterBinder#bindNull}
         * if you want typed nulls to bind successfully.
         *
         * @param elementType the element type of the array (may be primitive)
         * @param array       the array value to wrap; may be {@code null}
         * @return a {@link TypedParameter} representing an array suitable for use with custom binders
         */
        @NonNull
        public static TypedParameter arrayOf(@NonNull Class<?> elementType,
                                                                                                                                                         @Nullable Object array) {
                requireNonNull(elementType);

                if (array != null) {
                        Class<?> arrayClass = array.getClass();

                        if (!arrayClass.isArray())
                                throw new IllegalArgumentException("Array parameter is not an array");

                        Class<?> componentType = arrayClass.getComponentType();

                        if (elementType.isPrimitive()) {
                                if (!componentType.equals(elementType))
                                        throw new IllegalArgumentException("Array parameter component type does not match elementType");
                        } else if (!elementType.isAssignableFrom(componentType)) {
                                throw new IllegalArgumentException("Array parameter component type is not assignable to elementType");
                        }
                }

                Class<?> arrayType = Array.newInstance(elementType, 0).getClass();
                return new DefaultTypedParameter(arrayType, array);
        }

        /**
         * Acquires a vector parameter for an array of {@code double}.
         *
         * @param elements the elements of the vector parameter
         * @return the vector parameter
         */
        @NonNull
        public static VectorParameter vectorOfDoubles(double @Nullable [] elements) {
                return new DefaultVectorParameter(elements);
        }

        /**
         * Acquires a vector parameter for a {@link List} of {@link Double}.
         *
         * @param elements the elements of the vector parameter
         * @return the vector parameter
         */
        @NonNull
        public static VectorParameter vectorOfDoubles(@Nullable List<@NonNull Double> elements) {
                if (elements == null)
                        return new DefaultVectorParameter(null);

                double[] doubles = new double[elements.size()];
                for (int i = 0; i < doubles.length; i++) doubles[i] = requireNonNull(elements.get(i));
                return new DefaultVectorParameter(doubles);
        }

        /**
         * Acquires a vector parameter for an array of {@code float}.
         *
         * @param elements the elements of the vector parameter
         * @return the vector parameter
         */
        @NonNull
        public static VectorParameter vectorOfFloats(float @Nullable [] elements) {
                if (elements == null)
                        return new DefaultVectorParameter(null);

                double[] doubles = new double[elements.length];
                for (int i = 0; i < elements.length; i++) doubles[i] = elements[i];
                return new DefaultVectorParameter(doubles);
        }

        /**
         * Acquires a vector parameter for a {@link List} of {@link Float}.
         *
         * @param elements the elements of the vector parameter
         * @return the vector parameter
         */
        @NonNull
        public static VectorParameter vectorOfFloats(@Nullable List<@NonNull Float> elements) {
                if (elements == null)
                        return new DefaultVectorParameter(null);

                double[] doubles = new double[elements.size()];
                for (int i = 0; i < doubles.length; i++) doubles[i] = requireNonNull(elements.get(i));
                return new DefaultVectorParameter(doubles);
        }

        /**
         * Acquires a vector parameter for a {@link List} of {@link BigDecimal}.
         *
         * @param elements the elements of the vector parameter
         * @return the vector parameter
         */
        @NonNull
        public static VectorParameter vectorOfBigDecimals(@Nullable List<@NonNull BigDecimal> elements) {
                if (elements == null)
                        return new DefaultVectorParameter(null);

                double[] d = new double[elements.size()];
                for (int i = 0; i < d.length; i++) d[i] = requireNonNull(elements.get(i)).doubleValue();
                return new DefaultVectorParameter(d);
        }

        /**
         * Default package-private implementation of {@link VectorParameter}.
         *
         * @author <a href="https://www.revetkn.com">Mark Allen</a>
         * @since 3.0.0
         */
        @ThreadSafe
        static class DefaultVectorParameter implements VectorParameter {
                @Nullable
                private final double[] elements;

                private DefaultVectorParameter(double @Nullable [] elements) {
                        if (elements == null) {
                                this.elements = null;
                                return;
                        }

                        if (elements.length == 0)
                                throw new IllegalArgumentException("Vector parameters must have at least 1 element");

                        for (double d : elements)
                                if (!Double.isFinite(d))
                                        throw new IllegalArgumentException("Vector parameter elements must be finite (no NaN/Infinity)");

                        // Always defensive copy
                        this.elements = elements.clone();
                }

                /**
                 * Gets the elements of this vector.
                 *
                 * @return the elements of this vector
                 */
                @NonNull
                @Override
                public Optional<double[]> getElements() {
                        // Defensive copy
                        return this.elements == null ? Optional.empty() : Optional.of(this.elements.clone());
                }
        }

        /**
         * Acquires a JSON parameter for "stringified" JSON, using {@link BindingPreference#BINARY}.
         *
         * @param json the stringified JSON for this parameter
         * @return the JSON parameter
         */
        @NonNull
        public static JsonParameter json(@Nullable String json) {
                return new DefaultJsonParameter(json, BindingPreference.BINARY);
        }

        /**
         * Acquires a JSON parameter for "stringified" JSON.
         *
         * @param json              the stringified JSON for this parameter
         * @param bindingPreference how the JSON parameter should be bound to a {@link java.sql.PreparedStatement}
         * @return the JSON parameter
         */
        @NonNull
        public static JsonParameter json(@Nullable String json,
                                                                                                                                         @NonNull BindingPreference bindingPreference) {
                requireNonNull(bindingPreference);

                return new DefaultJsonParameter(json, bindingPreference);
        }

        /**
         * Default package-private implementation of {@link JsonParameter}.
         *
         * @author <a href="https://www.revetkn.com">Mark Allen</a>
         * @since 3.0.0
         */
        @ThreadSafe
        static class DefaultJsonParameter implements JsonParameter {
                @Nullable
                private final String json;
                @NonNull
                private final BindingPreference bindingPreference;

                private DefaultJsonParameter(@Nullable String json,
                                                                                                                                 @NonNull BindingPreference bindingPreference) {
                        requireNonNull(bindingPreference);

                        this.json = json;
                        this.bindingPreference = bindingPreference;
                }

                @NonNull
                @Override
                public Optional<String> getJson() {
                        return Optional.ofNullable(this.json);
                }

                @NonNull
                @Override
                public BindingPreference getBindingPreference() {
                        return this.bindingPreference;
                }
        }

        /**
         * Acquires a parameter of type {@link List}, preserving type information so it is accessible at runtime.
         * <p>
         * This is useful when you want to bind a parameterized collection such as {@code List<UUID>} or
         * {@code List<String>} and need the generic type argument (e.g. {@code UUID.class}) to be preserved.
         * <p>
         * The resulting {@link TypedParameter} carries both the runtime value and its generic type so that
         * {@link CustomParameterBinder#appliesTo(TargetType)} can match against the element type.
         * <p>
         * <strong>Note:</strong> this kind of parameter requires a corresponding {@link CustomParameterBinder}
         * to be registered, even when the wrapped value is {@code null}; implement {@link CustomParameterBinder#bindNull}
         * if you want typed nulls to bind successfully.
         *
         * @param elementType the {@link Class} representing the type of elements contained in the list;
         *                    used to preserve generic type information
         * @param list        the list value to wrap; may be {@code null}
         * @param <E>         the element type of the list
         * @return a {@link TypedParameter} representing a {@code List<E>} suitable for use with custom binders
         */
        @NonNull
        public static <E> TypedParameter listOf(@NonNull Class<E> elementType,
                                                                                                                                                                        @Nullable List<E> list) {
                requireNonNull(elementType);

                Type listOfE = new DefaultParameterizedType(List.class, new Type[]{elementType}, null);
                return new DefaultTypedParameter(listOfE, list);
        }

        /**
         * Acquires a parameter of type {@link Set}, preserving type information so it is accessible at runtime.
         * <p>
         * This is useful when you want to bind a parameterized collection such as {@code Set<UUID>} or
         * {@code Set<String>} and need the generic type argument (e.g. {@code UUID.class}) to be preserved.
         * <p>
         * The resulting {@link TypedParameter} carries both the runtime value and its generic type so that
         * {@link CustomParameterBinder#appliesTo(TargetType)} can match against the element type.
         * <p>
         * <strong>Note:</strong> this kind of parameter requires a corresponding {@link CustomParameterBinder}
         * to be registered, even when the wrapped value is {@code null}; implement {@link CustomParameterBinder#bindNull}
         * if you want typed nulls to bind successfully.
         *
         * @param elementType the {@link Class} representing the type of elements contained in the set;
         *                    used to preserve generic type information
         * @param set         the set value to wrap; may be {@code null}
         * @param <E>         the element type of the set
         * @return a {@link TypedParameter} representing a {@code Set<E>} suitable for use with custom binders
         */
        @NonNull
        public static <E> TypedParameter setOf(@NonNull Class<E> elementType,
                                                                                                                                                                 @Nullable Set<E> set) {
                requireNonNull(elementType);

                Type setOfE = new DefaultParameterizedType(Set.class, new Type[]{elementType}, null);
                return new DefaultTypedParameter(setOfE, set);
        }

        /**
         * Acquires a parameter of type {@link Map}, preserving key and value type information
         * so they are accessible at runtime.
         * <p>
         * This is useful when you want to bind a parameterized collection such as {@code Map<UUID, Integer>}
         * and need the generic type arguments (e.g. {@code UUID.class} and {@code Integer.class}) to be preserved.
         * <p>
         * The resulting {@link TypedParameter} carries both the runtime value and its generic type so that
         * {@link CustomParameterBinder#appliesTo(TargetType)} can match against the element type.
         * <p>
         * <strong>Note:</strong> this kind of parameter requires a corresponding {@link CustomParameterBinder}
         * to be registered, even when the wrapped value is {@code null}; implement {@link CustomParameterBinder#bindNull}
         * if you want typed nulls to bind successfully.
         *
         * @param keyType   the type of the map keys
         * @param valueType the type of the map values
         * @param map       the map value; may be {@code null}
         * @param <K>       the key type
         * @param <V>       the value type
         * @return a {@link TypedParameter} representing {@code Map<K,V>}
         */
        @NonNull
        public static <K, V> TypedParameter mapOf(@NonNull Class<K> keyType,
                                                                                                                                                                                @NonNull Class<V> valueType,
                                                                                                                                                                                @Nullable Map<K, V> map) {
                requireNonNull(keyType);
                requireNonNull(valueType);

                Type mapOfKV = new DefaultParameterizedType(Map.class, new Type[]{keyType, valueType}, null);
                return new DefaultTypedParameter(mapOfKV, map);
        }
}