qubit-codec 0.17.4

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================

//! Safe type-erased bidirectional string value-codec descriptors.

use core::any::type_name;
use core::fmt::Debug;
use core::fmt::Formatter;
use core::fmt::Result as FmtResult;
use std::any::Any;
use std::any::TypeId;
use std::borrow::Borrow;
use std::error::Error;

use crate::ValueCodecExecutionError;
use crate::ValueDecoder;
use crate::ValueEncoder;

/// Checked type-erased encoding entry point returning an owned string.
type EncodeFn = fn(&dyn Any) -> Result<String, ValueCodecExecutionError>;
/// Type-erased decoding entry point returning a boxed owned value.
type DecodeFn = fn(&str) -> Result<Box<dyn Any>, ValueCodecExecutionError>;

/// An immutable, safely erased bidirectional string codec for one value type.
///
/// Each operation creates a fresh default codec; no codec state is retained
/// between calls. Type identities are process-local and names are diagnostic,
/// not stable IDs.
///
/// # Examples
///
/// ```
/// use core::convert::Infallible;
///
/// use qubit_codec::ValueDecoder;
/// use qubit_codec::ValueEncoder;
/// use qubit_codec::ValueStringCodecDescriptor;
///
/// #[derive(Default)]
/// struct Text;
/// impl ValueEncoder<u32> for Text {
///     type Output = String;
///     type Error = Infallible;
///
///     fn encode(&mut self, input: &u32) -> Result<String, Infallible> {
///         Ok(input.to_string())
///     }
/// }
/// impl ValueDecoder<str> for Text {
///     type Output = u32;
///     type Error = Infallible;
///
///     fn decode(&mut self, input: &str) -> Result<u32, Infallible> {
///         Ok(input.len() as u32)
///     }
/// }
///
/// let descriptor = ValueStringCodecDescriptor::of::<Text, u32>();
///
/// // `encode` takes an erased `&dyn Any`, so the value type must be named.
/// let value: u32 = 7;
/// assert_eq!(descriptor.encode(&value).unwrap(), "7");
///
/// let decoded = descriptor.decode("hello").unwrap();
/// assert_eq!(*decoded.downcast::<u32>().unwrap(), 5);
/// ```
#[derive(Clone, Copy)]
pub struct ValueStringCodecDescriptor {
    /// Returns the process-local identity of the concrete codec.
    codec_type_id: fn() -> TypeId,
    /// Returns the diagnostic name of the concrete codec.
    codec_type_name: fn() -> &'static str,
    /// Returns the process-local identity of the decoded value.
    value_type_id: fn() -> TypeId,
    /// Returns the diagnostic name of the decoded value.
    value_type_name: fn() -> &'static str,
    /// Checks the erased input type and invokes a fresh default encoder.
    encode: EncodeFn,
    /// Invokes a fresh default decoder and boxes its owned output.
    decode: DecodeFn,
}

impl ValueStringCodecDescriptor {
    /// Creates a descriptor for codec `C` and value type `V`.
    ///
    /// The codec error types must implement `Send + Sync` so execution errors
    /// can retain their source across thread boundaries. The codec and value
    /// types themselves need not implement these traits; `V` only needs to be
    /// `'static` because decoded values are returned through `Any`.
    /// Use [`Self::of_borrowed`] when the encoder accepts a borrowed view of
    /// `V` instead of `V` itself.
    ///
    /// # Type Parameters
    ///
    /// - `C`: Default-constructible string encoder/decoder with owned errors.
    /// - `V`: Owned value type accepted and produced by `C`.
    ///
    /// # Returns
    ///
    /// Returns immutable function metadata without constructing a codec.
    #[must_use]
    #[inline]
    pub const fn of<C, V>() -> Self
    where
        C: Default + ValueEncoder<V, Output = String> + ValueDecoder<str, Output = V> + 'static,
        <C as ValueEncoder<V>>::Error: Error + Send + Sync + 'static,
        <C as ValueDecoder<str>>::Error: Error + Send + Sync + 'static,
        V: 'static,
    {
        Self::of_borrowed::<C, V, V>()
    }

    /// Creates a descriptor that encodes an owned value through a borrowed
    /// view.
    ///
    /// The descriptor continues to accept and return the owned type `V`.
    /// During each encode call it checks the erased value is exactly `V`, then
    /// borrows an `I` view with [`Borrow`] for that call only. The view is
    /// never stored. Each operation constructs a fresh `C::default()`
    /// codec. Encoder and decoder errors must implement `Error + Send +
    /// Sync + 'static`; `C` and `V` themselves need not be `Send` or
    /// `Sync`.
    ///
    /// # Type Parameters
    ///
    /// - `C`: Default-constructible codec encoding `I` and decoding into `V`.
    /// - `V`: Owned value type erased by this descriptor and produced by
    ///   decode.
    /// - `I`: Borrowed input view accepted by the encoder; it may be unsized.
    ///
    /// # Returns
    ///
    /// Returns immutable function metadata without constructing a codec.
    ///
    /// # Errors
    ///
    /// Encoding returns a type mismatch if the erased value is not `V`, or
    /// retains the codec's source error. Decoding retains the decoder's source
    /// error.
    ///
    /// # Examples
    ///
    /// ```
    /// use std::io::Error;
    /// use qubit_codec::{ValueDecoder, ValueEncoder, ValueStringCodecDescriptor};
    ///
    /// #[derive(Default)]
    /// struct Utf8;
    /// impl ValueEncoder<[u8]> for Utf8 {
    ///     type Output = String;
    ///     type Error = Error;
    ///     fn encode(&mut self, input: &[u8]) -> Result<String, Error> {
    ///         String::from_utf8(input.to_vec()).map_err(Error::other)
    ///     }
    /// }
    /// impl ValueDecoder<str> for Utf8 {
    ///     type Output = Vec<u8>;
    ///     type Error = Error;
    ///     fn decode(&mut self, input: &str) -> Result<Vec<u8>, Error> {
    ///         Ok(input.as_bytes().to_vec())
    ///     }
    /// }
    ///
    /// let descriptor = ValueStringCodecDescriptor::of_borrowed::<Utf8, Vec<u8>, [u8]>();
    /// let value = b"hello".to_vec();
    /// assert_eq!(descriptor.encode(&value).unwrap(), "hello");
    /// let decoded = descriptor.decode("hello").unwrap().downcast::<Vec<u8>>().unwrap();
    /// assert_eq!(*decoded, value);
    /// ```
    ///
    /// The owned type must implement [`Borrow`] for the selected input view,
    /// and the decoder output must be exactly `V`:
    ///
    /// ```compile_fail
    /// use std::io::Error;
    /// use qubit_codec::{ValueDecoder, ValueEncoder, ValueStringCodecDescriptor};
    ///
    /// #[derive(Default)] struct Codec;
    /// impl ValueEncoder<[u8]> for Codec {
    ///     type Output = String; type Error = Error;
    ///     fn encode(&mut self, input: &[u8]) -> Result<String, Error> {
    ///         String::from_utf8(input.to_vec()).map_err(Error::other)
    ///     }
    /// }
    /// impl ValueDecoder<str> for Codec {
    ///     type Output = String; type Error = Error;
    ///     fn decode(&mut self, input: &str) -> Result<String, Error> { Ok(input.to_owned()) }
    /// }
    /// let _ = ValueStringCodecDescriptor::of_borrowed::<Codec, String, [u8]>();
    /// ```
    ///
    /// ```compile_fail
    /// use std::io::Error;
    /// use qubit_codec::{ValueDecoder, ValueEncoder, ValueStringCodecDescriptor};
    ///
    /// #[derive(Default)] struct Codec;
    /// impl ValueEncoder<[u8]> for Codec {
    ///     type Output = String; type Error = Error;
    ///     fn encode(&mut self, input: &[u8]) -> Result<String, Error> {
    ///         String::from_utf8(input.to_vec()).map_err(Error::other)
    ///     }
    /// }
    /// impl ValueDecoder<str> for Codec {
    ///     type Output = String; type Error = Error;
    ///     fn decode(&mut self, input: &str) -> Result<String, Error> { Ok(input.to_owned()) }
    /// }
    /// let _ = ValueStringCodecDescriptor::of_borrowed::<Codec, Vec<u8>, [u8]>();
    /// ```
    #[must_use]
    #[inline]
    pub const fn of_borrowed<C, V, I>() -> Self
    where
        C: Default + ValueEncoder<I, Output = String> + ValueDecoder<str, Output = V> + 'static,
        <C as ValueEncoder<I>>::Error: Error + Send + Sync + 'static,
        <C as ValueDecoder<str>>::Error: Error + Send + Sync + 'static,
        V: Borrow<I> + 'static,
        I: ?Sized,
    {
        Self {
            codec_type_id: TypeId::of::<C>,
            codec_type_name: type_name::<C>,
            value_type_id: TypeId::of::<V>,
            value_type_name: type_name::<V>,
            encode: encode::<C, V, I>,
            decode: decode::<C, V>,
        }
    }

    /// Returns the process-local identity of the concrete codec.
    ///
    /// # Returns
    ///
    /// Returns the `TypeId` of the codec this descriptor was built for.
    #[must_use]
    #[inline]
    pub fn codec_type_id(&self) -> TypeId {
        (self.codec_type_id)()
    }

    /// Returns the diagnostic name of the concrete codec.
    ///
    /// # Returns
    ///
    /// Returns the `type_name` of the codec, for diagnostics only.
    #[must_use]
    #[inline]
    pub fn codec_type_name(&self) -> &'static str {
        (self.codec_type_name)()
    }

    /// Returns the process-local identity of the decoded value.
    ///
    /// # Returns
    ///
    /// Returns the `TypeId` of the value this descriptor accepts and produces.
    #[must_use]
    #[inline]
    pub fn value_type_id(&self) -> TypeId {
        (self.value_type_id)()
    }

    /// Returns the diagnostic name of the decoded value.
    ///
    /// # Returns
    ///
    /// Returns the `type_name` of the value, for diagnostics only.
    #[must_use]
    #[inline]
    pub fn value_type_name(&self) -> &'static str {
        (self.value_type_name)()
    }

    /// Encodes one erased value after checking its concrete type.
    ///
    /// # Parameters
    ///
    /// - `value`: Borrowed value whose concrete type must match the descriptor.
    ///
    /// # Returns
    ///
    /// Returns an owned string produced by a fresh default codec.
    ///
    /// # Errors
    ///
    /// Returns a type mismatch or the typed encoder source error.
    #[inline]
    pub fn encode(&self, value: &dyn Any) -> Result<String, ValueCodecExecutionError> {
        (self.encode)(value)
    }

    /// Decodes one string into a safely erased value of the declared type.
    ///
    /// # Parameters
    ///
    /// - `input`: String borrowed for one decoding operation.
    ///
    /// # Returns
    ///
    /// Returns a boxed owned value that can be downcast to the declared type.
    ///
    /// # Errors
    ///
    /// Returns the typed decoder source error.
    #[inline]
    pub fn decode(&self, input: &str) -> Result<Box<dyn Any>, ValueCodecExecutionError> {
        (self.decode)(input)
    }
}

impl Debug for ValueStringCodecDescriptor {
    /// Formats descriptor metadata without invoking either codec function.
    ///
    /// # Parameters
    ///
    /// - `formatter`: Destination receiving the diagnostic type names.
    ///
    /// # Returns
    ///
    /// Returns success after both names have been formatted.
    ///
    /// # Errors
    ///
    /// Returns the underlying formatting failure.
    fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
        formatter
            .debug_struct("ValueStringCodecDescriptor")
            .field("codec_type_name", &self.codec_type_name())
            .field("value_type_name", &self.value_type_name())
            .finish_non_exhaustive()
    }
}

/// Downcasts an erased value and encodes it with a fresh default codec.
///
/// # Type Parameters
///
/// - `C`: Default codec encoding the selected borrowed view.
/// - `V`: Concrete owned value type required by the descriptor.
/// - `I`: Borrowed input view accepted by the encoder.
///
/// # Parameters
///
/// - `value`: Erased input borrowed until serialization completes.
///
/// # Returns
///
/// Returns the owned string produced by the codec.
///
/// # Errors
///
/// Returns `TypeMismatch` when the input has a different concrete type, or
/// `EncodeFailed` with the codec source error when encoding fails.
fn encode<C, V, I>(value: &dyn Any) -> Result<String, ValueCodecExecutionError>
where
    C: Default + ValueEncoder<I, Output = String>,
    <C as ValueEncoder<I>>::Error: Error + Send + Sync + 'static,
    V: Borrow<I> + 'static,
    I: ?Sized,
{
    let value = value
        .downcast_ref::<V>()
        .ok_or_else(|| ValueCodecExecutionError::TypeMismatch {
            expected_type: type_name::<V>(),
            actual_type: value.type_id(),
        })?;
    <C as ValueEncoder<I>>::encode(&mut C::default(), <V as Borrow<I>>::borrow(value)).map_err(|source| {
        ValueCodecExecutionError::EncodeFailed {
            codec_type: type_name::<C>(),
            source: Box::new(source),
        }
    })
}

/// Decodes one string with a fresh default codec and erases its typed output.
///
/// # Type Parameters
///
/// - `C`: Default codec with matching string encode/decode contracts.
/// - `V`: Concrete owned value type produced by the descriptor.
///
/// # Parameters
///
/// - `input`: String slice borrowed until decoding completes.
///
/// # Returns
///
/// Returns the decoded value in a box that can be downcast to `V`.
///
/// # Errors
///
/// Returns `DecodeFailed` with the codec source error when decoding fails.
fn decode<C, V>(input: &str) -> Result<Box<dyn Any>, ValueCodecExecutionError>
where
    C: Default + ValueDecoder<str, Output = V>,
    <C as ValueDecoder<str>>::Error: Error + Send + Sync + 'static,
    V: 'static,
{
    C::default()
        .decode(input)
        .map(|value| Box::new(value) as Box<dyn Any>)
        .map_err(|source| ValueCodecExecutionError::DecodeFailed {
            codec_type: type_name::<C>(),
            source: Box::new(source),
        })
}