Skip to main content
Version: 11.x

Class: CairoTypeCustomEnum

Defined in: src/utils/cairoDataTypes/cairoTypeCustomEnum.ts:46

A Cairo custom enum : one of several named variants, each carrying its own type.

On the wire it is the index of the active variant, then that variant's value. Which variant is meant cannot be read off the value, so building one from raw data asks for the index — unless the content is a CairoCustomEnum, which names its own active variant.

Like a struct, a custom enum has no shape to recognize : its abi type is the name the contract chose. It is found by that exact name among a strategy's constructors, which is what enumStrategy builds from an abi.

Example​

const abiEnum: AbiEnum = {
  type: 'enum',
  name: 'test::MyEnum',
  variants: [
    { name: 'Empty', type: '()' },
    { name: 'Number', type: 'core::integer::u8' },
  ],
};
const strategies = [cairoTypeStrategy, enumStrategy([abiEnum])];
new CairoTypeCustomEnum(7, abiEnum, strategies, 1).toApiRequest();
// ["1", "7"]

Constructors​

Constructor​

new CairoTypeCustomEnum(content, abiEnum, parsingStrategy, variant?, subType?): CairoTypeCustomEnum

Defined in: src/utils/cairoDataTypes/cairoTypeCustomEnum.ts:118

Build a custom enum, from a value a caller passed or from the felts of a response.

A CairoCustomEnum names its own active variant, so variant must be left out with one — as with the response iterator and with a CairoTypeCustomEnum being copied. Anywhere else it is required, the index being the only thing that says which variant a value belongs to.

A CairoOption or a CairoResult is turned into its own Cairo type here rather than through the strategy : the strategy is handed variant, and those two would read it as their own branch instead of as the enum's index.

subType is what makes an enum of enums work. Handed a CairoCustomEnum, this constructor unwraps it and calls itself with what was inside; the flag stops that second call from unwrapping again and losing a level.

Parameters​

content​

unknown

the value, a CairoCustomEnum, an instance already built, or the response iterator

abiEnum​

AbiEnum

the abi definition of this enum

parsingStrategy​

AllowArray<CairoTypeStrategy>

how to build the variant's value

variant?​

number

the index of the active variant, when the content does not say

subType?​

boolean = false

true when called from the unwrapping of a nested CairoCustomEnum, which is the only caller that should set it

Returns​

CairoTypeCustomEnum

Throws​

when the content is missing, the variant is missing or out of range, or the variant type is one no strategy knows

Example​

new CairoTypeCustomEnum(7, abiEnum, strategies, 1).toApiRequest();
// ["1", "7"]
new CairoTypeCustomEnum(new CairoCustomEnum({ Number: 7 }), abiEnum, strategies).toApiRequest();
// ["1", "7"]     the CairoCustomEnum names its own variant

Properties​

dynamicSelector​

readonly dynamicSelector: string

Defined in: src/utils/cairoDataTypes/cairoTypeCustomEnum.ts:55

The name this enum is registered under, which is the name the abi gave it.

Example​

const result = new CairoTypeCustomEnum(7, abiEnum, strategies, 1).dynamicSelector;
// result = "test::MyEnum"

content​

readonly content: CairoType

Defined in: src/utils/cairoDataTypes/cairoTypeCustomEnum.ts:65

The value the active variant carries.

Example​

const result = new CairoTypeCustomEnum(7, abiEnum, strategies, 1).content.toApiRequest();
// result = ["7"]

abiEnum​

readonly abiEnum: AbiEnum

Defined in: src/utils/cairoDataTypes/cairoTypeCustomEnum.ts:75

The abi definition this enum was built from.

Example​

const result = new CairoTypeCustomEnum(7, abiEnum, strategies, 1).abiEnum.name;
// result = "test::MyEnum"

enumVariant​

readonly enumVariant: number

Defined in: src/utils/cairoDataTypes/cairoTypeCustomEnum.ts:85

The index of the active variant, in the abi's order.

Example​

const result = new CairoTypeCustomEnum(7, abiEnum, strategies, 1).enumVariant;
// result = 1

Methods​

validate()​

static validate(_input, type, _variant): void

Defined in: src/utils/cairoDataTypes/cairoTypeCustomEnum.ts:285

Throw unless this name can be a Cairo 1 type at all.

There is nothing more to check : a custom enum's abi type is the name the contract chose, and what the value is worth is the business of the active variant's type.

Parameters​

_input​

unknown

the value, which this does not read

type​

string

the abi name it is meant for

_variant​

VariantType | undefined

the variant, which this does not read

Returns​

void

Throws​

when the name is not a Cairo 1 type name

Example​

CairoTypeCustomEnum.validate(7, 'test::MyEnum', 1); // passes
CairoTypeCustomEnum.validate(7, 'wrong', 1);
// throws Error("The type wrong is not a Cairo Enum. Needs impl::name.")

is()​

static is(input, type, variant): boolean

Defined in: src/utils/cairoDataTypes/cairoTypeCustomEnum.ts:308

Can this name be a Cairo custom enum?

The non-throwing form of CairoTypeCustomEnum.validate.

Parameters​

input​

unknown

the value to test

type​

string

the abi name it is meant for

variant​

VariantType

the variant

Returns​

boolean

true when the name could be one

Example​

const result = CairoTypeCustomEnum.is(7, 'test::MyEnum', 1);
// result = true
const result2 = CairoTypeCustomEnum.is(7, 'wrong', 1);
// result2 = false

isAbiType()​

static isAbiType(type): boolean

Defined in: src/utils/cairoDataTypes/cairoTypeCustomEnum.ts:333

Could this abi type name a Cairo custom enum?

Only the shape of the name is testable — a custom enum has no pattern of its own, so this says no more than that the name looks like a Cairo 1 type. It is deliberately not used as a dynamic selector : one that answered true this widely would shadow every other type.

Parameters​

type​

string

the abi type to test

Returns​

boolean

true when the name contains ::

Example​

const result = CairoTypeCustomEnum.isAbiType('my_contract::my_enum');
// result = true
const result2 = CairoTypeCustomEnum.isAbiType('wrong');
// result2 = false

getVariantTypes()​

static getVariantTypes(type): string[]

Defined in: src/utils/cairoDataTypes/cairoTypeCustomEnum.ts:347

The types of the variants, in the abi's order.

Parameters​

type​

AbiEnum

the abi definition to read

Returns​

string[]

one type per variant

Example​

const result = CairoTypeCustomEnum.getVariantTypes(abiEnum);
// result = ["()", "core::integer::u8"]

extractEnumMembersNames()​

static extractEnumMembersNames(type): string[]

Defined in: src/utils/cairoDataTypes/cairoTypeCustomEnum.ts:361

The names of the variants, in the abi's order.

Parameters​

type​

AbiEnum

the abi definition to read

Returns​

string[]

one name per variant

Example​

const result = CairoTypeCustomEnum.extractEnumMembersNames(abiEnum);
// result = ["Empty", "Number"]

toApiRequest()​

toApiRequest(): string[]

Defined in: src/utils/cairoDataTypes/cairoTypeCustomEnum.ts:376

Serialize to the felts a contract call carries.

The index of the active variant comes first, then its value.

Returns​

string[]

the variant index then the value, flagged as compiled

Example​

const result = new CairoTypeCustomEnum(7, abiEnum, strategies, 1).toApiRequest();
// result = ["1", "7"]

decompose()​

decompose(strategyDecompose): CairoCustomEnum

Defined in: src/utils/cairoDataTypes/cairoTypeCustomEnum.ts:396

Read the enum back as the CairoCustomEnum a caller reads.

Every variant the abi declares appears in the result, the inactive ones as undefined — which is how CairoCustomEnum tells which one is active.

Parameters​

strategyDecompose​

AllowArray<CairoTypeStrategy>

how to read the value back

Returns​

CairoCustomEnum

the enum, with its active variant carrying the value

Throws​

when no strategy can read the value back

Example​

const result = new CairoTypeCustomEnum(7, abiEnum, strategies, 1).decompose(strategies);
// result = CairoCustomEnum { Empty: undefined, Number: 7n }