Trait MagicInstantiate

Source

pub trait MagicInstantiate: Any + Sized {
    // Required methods
    fn definition() -> String;
    fn reference() -> String;
    fn name() -> String;
    fn add_dependencies(builder: &mut TypeScriptAccumulator);
    fn validate(value: &JsonValue) -> Result<Self, String>;
    fn default_if_omitted() -> Option<Self>;
    fn is_object() -> bool;

    // Provided method
    fn prompt_for(instructions: &str) -> String { ... }
}

Expand description

The MagicInstantiate trait is the main trait of this library, but you should not need to implement it manually. Prefer using the #[derive(MagicInstantiate)] macro instead.

If you must implement it manually, here is an example:

use openai_magic_instantiate::*;
use openai_magic_instantiate::export::JsonValue;
 
struct Person {
    name: String,
    year_of_birth: u32,
}
 
impl MagicInstantiate for Person {
    fn definition() -> String {
        let string_ref = <String>::reference();
        let u32_ref = <u32>::reference();
        // Must use {{ to escape the curly braces
        format!("
type Person = {{
    // <given name> <surname> (no middle)
    name: {string_ref};
    // Value must be a 4-digit year, do not use 2-digit abbreviations
    yearOfBirth: {u32_ref};
}};
        ").trim().to_string()
    }
 
    fn name() -> String {
        "Person".to_string()
    }
 
    fn reference() -> String {
        // Since we defined a type, `reference` is the same as `name`
        // This will be the case for all structs and enums
        Self::name()
    }
 
    fn add_dependencies(builder: &mut TypeScriptAccumulator) {
        // We need to add all the types that are fields of this type
        builder.add::<String>();
        builder.add::<u32>();
    }
 
    fn validate(value: &JsonValue) -> Result<Self, String> {
        let JsonValue::Object(value) = value else {
            return Err("Expected object with fields [\"name\", \"yearOfBirth\"]".to_string());
        };
        let result = Self {
            name: {
                let value = value.get("name").ok_or("Expected field name, but it wasn't present")?;
                <String>::validate(value)?
            },
            year_of_birth: {
                let value = value.get("yearOfBirth").ok_or("Expected field yearOfBirth, but it wasn't present")?;
                let value = <u32>::validate(value)?;
                if value < 1000 || value > 9999 {
                    return Err(format!("{} is not a 4-digit year", value));
                }
                value
            },
        };
        Ok(result)
    }
 
    fn default_if_omitted() -> Option<Self> {
        None
    }
 
   fn is_object() -> bool {
       true
   }
}

Required Methods§

Source

fn definition() -> String

The TypeScript definition of the type if it needs one.

For example:

type Person = {
    name: string;
    // Value must be a 4-digit year, do not use 2-digit abbreviations
    age: number;
};

Note that the definition should include helpful comments.

Note that the definition might be empty. For example, f64’s implementation of this method is empty, because the reference is just the TypeScript primitive number.

Source

fn reference() -> String

How the type should be referred to in other types.

If the type returns a definition, this should be the same as the type name in the definition.

If the type does not return a definition, this should be some type that is valid in vanilla TypeScript. For example, Array<[string, number]>, "myEnumKind", and string | null are all valid references.

Source

fn name() -> String

Name of the type if it needed to be referred to in another type name.

Even types that don’t need a definition should have a name. For example, the Rust type Option<String> doesn’t need a definition and just uses a reference of string | null, but this method returns the name OptionalString.

This is needed because another type’s name might depend on this type’s name. For example, MyCollection<Option<String>> might be named MyCollectionOfOptionalString.

Source

fn add_dependencies(builder: &mut TypeScriptAccumulator)

If this type is non-primitive, it contains some other types as fields. This method should call builder.add::<T>() for each field type T.

Source

fn validate(value: &JsonValue) -> Result<Self, String>

Validate a JSON value and convert it to the type, return a helpful error message if the value is invalid.

Source

fn default_if_omitted() -> Option<Self>

If the value is omitted, what the default is. Most objects should return None because they are not optional. Option<T> returns Some(None), that is, omitting a field with type Option<T>`` is the same as including the field with value NoneAnother case you might want to returnSome` is for a collection type where omission defaults to the empty collection.

Source

fn is_object() -> bool

Whether or not this type maps to a TypeScript object.

This is needed because OpenAI JSON mode can only generate objects, so if the user tries to instantiate a bool, this library must internally convert it to an object with a single field, e.g. { value: bool } and then unwrap it back to a bool for validation.

Provided Methods§

Source

fn prompt_for(instructions: &str) -> String

Convert this type into a prompt for the LLM.

The default implementation is pretty good and you probably don’t need to override it.

This method is exposed mostly for debugging purposes.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Trait MagicInstantiateCopy item path

Required Methods§

fn definition() -> String

fn reference() -> String

fn name() -> String

fn add_dependencies(builder: &mut TypeScriptAccumulator)

fn validate(value: &JsonValue) -> Result<Self, String>

fn default_if_omitted() -> Option<Self>

fn is_object() -> bool

Provided Methods§

fn prompt_for(instructions: &str) -> String

Dyn Compatibility§

Implementations on Foreign Types§

impl MagicInstantiate for bool

fn name() -> String

fn reference() -> String

fn definition() -> String

fn add_dependencies(_builder: &mut TypeScriptAccumulator)

fn validate(value: &JsonValue) -> Result<Self, String>

fn default_if_omitted() -> Option<Self>

fn is_object() -> bool

impl MagicInstantiate for f32

fn name() -> String

fn reference() -> String

fn definition() -> String

fn add_dependencies(_builder: &mut TypeScriptAccumulator)

fn validate(value: &JsonValue) -> Result<Self, String>

fn default_if_omitted() -> Option<Self>

fn is_object() -> bool

impl MagicInstantiate for f64

fn name() -> String

fn reference() -> String

fn definition() -> String

fn add_dependencies(_builder: &mut TypeScriptAccumulator)

fn validate(value: &JsonValue) -> Result<Self, String>

fn default_if_omitted() -> Option<Self>

fn is_object() -> bool

impl MagicInstantiate for i8

fn name() -> String

fn reference() -> String

fn definition() -> String

fn add_dependencies(builder: &mut TypeScriptAccumulator)

fn validate(value: &JsonValue) -> Result<Self, String>

fn default_if_omitted() -> Option<Self>

fn is_object() -> bool

impl MagicInstantiate for i16

fn name() -> String

fn reference() -> String

fn definition() -> String

fn add_dependencies(builder: &mut TypeScriptAccumulator)

fn validate(value: &JsonValue) -> Result<Self, String>

fn default_if_omitted() -> Option<Self>

fn is_object() -> bool

impl MagicInstantiate for i32

fn name() -> String

fn reference() -> String

fn definition() -> String

fn add_dependencies(builder: &mut TypeScriptAccumulator)

fn validate(value: &JsonValue) -> Result<Self, String>

fn default_if_omitted() -> Option<Self>

fn is_object() -> bool

impl MagicInstantiate for i64

fn name() -> String

fn reference() -> String

fn definition() -> String

fn add_dependencies(builder: &mut TypeScriptAccumulator)

fn validate(value: &JsonValue) -> Result<Self, String>

fn default_if_omitted() -> Option<Self>

fn is_object() -> bool

impl MagicInstantiate for isize

fn name() -> String

fn reference() -> String

fn definition() -> String

fn add_dependencies(builder: &mut TypeScriptAccumulator)

fn validate(value: &JsonValue) -> Result<Self, String>

fn default_if_omitted() -> Option<Self>

fn is_object() -> bool

impl MagicInstantiate for u8

fn name() -> String

fn reference() -> String

Trait MagicInstantiate