@dfinity/candid/lib/esm/idl.d.ts

JavaScript and TypeScript library to work with candid interfaces

import { Principal as PrincipalId } from '@dfinity/principal';
import { type JsonValue } from './types.ts';
import { PipeArrayBuffer as Pipe } from './utils/buffer.ts';
/**
 * An IDL Type Table, which precedes the data in the stream.
 */
declare class TypeTable {
    private _typs;
    private _idx;
    private _idxRefCount;
    has(obj: ConstructType): boolean;
    add<T>(type: ConstructType<T>, buf: Uint8Array): void;
    merge<T>(obj: ConstructType<T>, knot: string): void;
    private _getIdxRefCount;
    private _compactFromEnd;
    encode(): Uint8Array;
    indexOf(typeName: string): Uint8Array;
}
export declare abstract class Visitor<D, R> {
    visitType<T>(_t: Type<T>, _data: D): R;
    visitPrimitive<T>(t: PrimitiveType<T>, data: D): R;
    visitEmpty(t: EmptyClass, data: D): R;
    visitBool(t: BoolClass, data: D): R;
    visitNull(t: NullClass, data: D): R;
    visitReserved(t: ReservedClass, data: D): R;
    visitText(t: TextClass, data: D): R;
    visitNumber<T>(t: PrimitiveType<T>, data: D): R;
    visitInt(t: IntClass, data: D): R;
    visitNat(t: NatClass, data: D): R;
    visitFloat(t: FloatClass, data: D): R;
    visitFixedInt(t: FixedIntClass, data: D): R;
    visitFixedNat(t: FixedNatClass, data: D): R;
    visitPrincipal(t: PrincipalClass, data: D): R;
    visitConstruct<T>(t: ConstructType<T>, data: D): R;
    visitVec<T>(t: VecClass<T>, _ty: Type<T>, data: D): R;
    visitOpt<T>(t: OptClass<T>, _ty: Type<T>, data: D): R;
    visitRecord(t: RecordClass, _fields: Array<[string, Type]>, data: D): R;
    visitTuple<T extends any[]>(t: TupleClass<T>, components: Type[], data: D): R;
    visitVariant(t: VariantClass, _fields: Array<[string, Type]>, data: D): R;
    visitRec<T>(_t: RecClass<T>, ty: ConstructType<T>, data: D): R;
    visitFunc(t: FuncClass, data: D): R;
    visitService(t: ServiceClass, data: D): R;
}
declare enum IdlTypeName {
    EmptyClass = "__IDL_EmptyClass__",
    UnknownClass = "__IDL_UnknownClass__",
    BoolClass = "__IDL_BoolClass__",
    NullClass = "__IDL_NullClass__",
    ReservedClass = "__IDL_ReservedClass__",
    TextClass = "__IDL_TextClass__",
    IntClass = "__IDL_IntClass__",
    NatClass = "__IDL_NatClass__",
    FloatClass = "__IDL_FloatClass__",
    FixedIntClass = "__IDL_FixedIntClass__",
    FixedNatClass = "__IDL_FixedNatClass__",
    VecClass = "__IDL_VecClass__",
    OptClass = "__IDL_OptClass__",
    RecordClass = "__IDL_RecordClass__",
    TupleClass = "__IDL_TupleClass__",
    VariantClass = "__IDL_VariantClass__",
    RecClass = "__IDL_RecClass__",
    PrincipalClass = "__IDL_PrincipalClass__",
    FuncClass = "__IDL_FuncClass__",
    ServiceClass = "__IDL_ServiceClass__"
}
/**
 * Represents an IDL type.
 */
export declare abstract class Type<T = any> {
    abstract readonly typeName: IdlTypeName;
    abstract readonly name: string;
    abstract accept<D, R>(v: Visitor<D, R>, d: D): R;
    display(): string;
    valueToString(x: T): string;
    buildTypeTable(typeTable: TypeTable): void;
    /**
     * Assert that JavaScript's `x` is the proper type represented by this
     * Type.
     */
    abstract covariant(x: any): x is T;
    /**
     * Encode the value. This needs to be public because it is used by
     * encodeValue() from different types.
     * @internal
     */
    abstract encodeValue(x: T): Uint8Array;
    /**
     * Implement `I` in the IDL spec.
     * Encode this type for the type table.
     */
    abstract encodeType(typeTable: TypeTable): Uint8Array;
    abstract checkType(t: Type): Type;
    abstract decodeValue(x: Pipe, t: Type): T;
    protected abstract _buildTypeTableImpl(typeTable: TypeTable): void;
}
export declare abstract class PrimitiveType<T = any> extends Type<T> {
    checkType(t: Type): Type;
    _buildTypeTableImpl(_typeTable: TypeTable): void;
}
export declare abstract class ConstructType<T = any> extends Type<T> {
    checkType(t: Type): ConstructType<T>;
    encodeType(typeTable: TypeTable): Uint8Array<ArrayBufferLike>;
}
/**
 * Represents an IDL Empty, a type which has no inhabitants.
 * Since no values exist for this type, it cannot be serialised or deserialised.
 * Result types like `Result<Text, Empty>` should always succeed.
 */
export declare class EmptyClass extends PrimitiveType<never> {
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance](instance: any): instance is EmptyClass;
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    covariant(x: any): x is never;
    encodeValue(): never;
    valueToString(): never;
    encodeType(): Uint8Array<ArrayBufferLike>;
    decodeValue(): never;
    get name(): string;
}
/**
 * Represents an IDL Unknown, a placeholder type for deserialization only.
 * When decoding a value as Unknown, all fields will be retained but the names are only available in
 * hashed form.
 * A deserialized unknown will offer it's actual type by calling the `type()` function.
 * Unknown cannot be serialized and attempting to do so will throw an error.
 */
export declare class UnknownClass extends Type {
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance](instance: any): instance is UnknownClass;
    checkType(_t: Type): Type;
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    covariant(x: any): x is any;
    encodeValue(): never;
    valueToString(): never;
    encodeType(): never;
    decodeValue(b: Pipe, t: Type): any;
    protected _buildTypeTableImpl(): void;
    get name(): string;
}
/**
 * Represents an IDL Bool
 */
export declare class BoolClass extends PrimitiveType<boolean> {
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance](instance: any): instance is BoolClass;
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    covariant(x: any): x is boolean;
    encodeValue(x: boolean): Uint8Array;
    encodeType(): Uint8Array;
    decodeValue(b: Pipe, t: Type): boolean;
    get name(): string;
}
/**
 * Represents an IDL Null
 */
export declare class NullClass extends PrimitiveType<null> {
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance](instance: any): instance is NullClass;
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    covariant(x: any): x is null;
    encodeValue(): Uint8Array;
    encodeType(): Uint8Array;
    decodeValue(_b: Pipe, t: Type): null;
    get name(): string;
}
/**
 * Represents an IDL Reserved
 */
export declare class ReservedClass extends PrimitiveType<any> {
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance](instance: any): instance is ReservedClass;
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    covariant(_x: any): _x is any;
    encodeValue(): Uint8Array;
    encodeType(): Uint8Array;
    decodeValue(b: Pipe, t: Type): null;
    get name(): string;
}
/**
 * Represents an IDL Text
 */
export declare class TextClass extends PrimitiveType<string> {
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance](instance: any): instance is TextClass;
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    covariant(x: any): x is string;
    encodeValue(x: string): Uint8Array<ArrayBufferLike>;
    encodeType(): Uint8Array<ArrayBufferLike>;
    decodeValue(b: Pipe, t: Type): string;
    get name(): string;
    valueToString(x: string): string;
}
/**
 * Represents an IDL Int
 */
export declare class IntClass extends PrimitiveType<bigint> {
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance](instance: any): instance is IntClass;
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    covariant(x: any): x is bigint;
    encodeValue(x: bigint | number): Uint8Array;
    encodeType(): Uint8Array<ArrayBufferLike>;
    decodeValue(b: Pipe, t: Type): bigint;
    get name(): string;
    valueToString(x: bigint): string;
}
/**
 * Represents an IDL Nat
 */
export declare class NatClass extends PrimitiveType<bigint> {
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance](instance: any): instance is NatClass;
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    covariant(x: any): x is bigint;
    encodeValue(x: bigint | number): Uint8Array;
    encodeType(): Uint8Array<ArrayBufferLike>;
    decodeValue(b: Pipe, t: Type): bigint;
    get name(): string;
    valueToString(x: bigint): string;
}
/**
 * Represents an IDL Float
 */
export declare class FloatClass extends PrimitiveType<number> {
    readonly _bits: number;
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance](instance: any): instance is FloatClass;
    constructor(_bits: number);
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    covariant(x: any): x is number;
    encodeValue(x: number): Uint8Array<ArrayBuffer>;
    encodeType(): Uint8Array;
    decodeValue(b: Pipe, t: Type): number;
    get name(): string;
    valueToString(x: number): string;
}
/**
 * Represents an IDL fixed-width Int(n)
 */
export declare class FixedIntClass extends PrimitiveType<bigint | number> {
    readonly _bits: number;
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance](instance: any): instance is FixedIntClass;
    constructor(_bits: number);
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    covariant(x: any): x is bigint;
    encodeValue(x: bigint | number): Uint8Array<ArrayBufferLike>;
    encodeType(): Uint8Array<ArrayBufferLike>;
    decodeValue(b: Pipe, t: Type): number | bigint;
    get name(): string;
    valueToString(x: bigint | number): string;
}
/**
 * Represents an IDL fixed-width Nat(n)
 */
export declare class FixedNatClass extends PrimitiveType<bigint | number> {
    readonly _bits: number;
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance](instance: any): instance is FixedNatClass;
    constructor(_bits: number);
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    covariant(x: any): x is bigint;
    encodeValue(x: bigint | number): Uint8Array<ArrayBufferLike>;
    encodeType(): Uint8Array<ArrayBufferLike>;
    decodeValue(b: Pipe, t: Type): number | bigint;
    get name(): string;
    valueToString(x: bigint | number): string;
}
/**
 * Represents an IDL Array
 *
 * Arrays of fixed-sized nat/int type (e.g. nat8), are encoded from and decoded to TypedArrays (e.g. Uint8Array).
 * Arrays of float or other non-primitive types are encoded/decoded as untyped array in Javascript.
 * @param {Type} t
 */
export declare class VecClass<T> extends ConstructType<T[]> {
    _type: Type<T>;
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance]<T>(instance: any): instance is VecClass<T>;
    private _blobOptimization;
    constructor(_type: Type<T>);
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    covariant(x: any): x is T[];
    encodeValue(x: T[]): Uint8Array;
    _buildTypeTableImpl(typeTable: TypeTable): void;
    decodeValue(b: Pipe, t: Type): T[];
    get name(): string;
    display(): string;
    valueToString(x: T[]): string;
}
/**
 * Represents an IDL Option
 * @param {Type} t
 */
export declare class OptClass<T> extends ConstructType<[T] | []> {
    _type: Type<T>;
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance]<T>(instance: any): instance is OptClass<T>;
    constructor(_type: Type<T>);
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    covariant(x: any): x is [T] | [];
    encodeValue(x: [T] | []): Uint8Array;
    _buildTypeTableImpl(typeTable: TypeTable): void;
    decodeValue(b: Pipe, t: Type): [T] | [];
    get name(): string;
    display(): string;
    valueToString(x: [T] | []): string;
}
/**
 * Represents an IDL Record
 * @param {object} [fields] - mapping of function name to Type
 */
export declare class RecordClass extends ConstructType<Record<string, any>> {
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance](instance: any): instance is RecordClass;
    readonly _fields: Array<[string, Type]>;
    constructor(fields?: Record<string, Type>);
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    tryAsTuple(): Type[] | null;
    covariant(x: any): x is Record<string, any>;
    encodeValue(x: Record<string, any>): Uint8Array;
    _buildTypeTableImpl(T: TypeTable): void;
    decodeValue(b: Pipe, t: Type): Record<string, any>;
    get fieldsAsObject(): Record<number, Type>;
    get name(): string;
    display(): string;
    valueToString(x: Record<string, any>): string;
}
/**
 * Represents Tuple, a syntactic sugar for Record.
 * @param {Type} components
 */
export declare class TupleClass<T extends any[]> extends RecordClass {
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance]<T extends any[]>(instance: any): instance is TupleClass<T>;
    protected readonly _components: Type[];
    constructor(_components: Type[]);
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    covariant(x: any): x is T;
    encodeValue(x: any[]): Uint8Array;
    decodeValue(b: Pipe, t: Type): T;
    display(): string;
    valueToString(values: any[]): string;
}
/**
 * Represents an IDL Variant
 * @param {object} [fields] - mapping of function name to Type
 */
export declare class VariantClass extends ConstructType<Record<string, any>> {
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance](instance: any): instance is VariantClass;
    readonly _fields: Array<[string, Type]>;
    constructor(fields?: Record<string, Type>);
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    covariant(x: any): x is Record<string, any>;
    encodeValue(x: Record<string, any>): Uint8Array<ArrayBufferLike>;
    _buildTypeTableImpl(typeTable: TypeTable): void;
    decodeValue(b: Pipe, t: Type): {
        [x: string]: any;
    };
    get name(): string;
    display(): string;
    valueToString(x: Record<string, any>): string;
    get alternativesAsObject(): Record<number, Type>;
}
/**
 * Represents a reference to an IDL type, used for defining recursive data
 * types.
 */
export declare class RecClass<T = any> extends ConstructType<T> {
    get typeName(): IdlTypeName;
    private static _counter;
    private _id;
    private _type;
    static [Symbol.hasInstance](instance: any): instance is RecClass;
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    fill(t: ConstructType<T>): void;
    getType(): ConstructType<T> | undefined;
    covariant(x: any): x is T;
    encodeValue(x: T): Uint8Array<ArrayBufferLike>;
    _buildTypeTableImpl(typeTable: TypeTable): void;
    decodeValue(b: Pipe, t: Type): T;
    get name(): string;
    display(): string;
    valueToString(x: T): string;
}
/**
 * Represents an IDL principal reference
 */
export declare class PrincipalClass extends PrimitiveType<PrincipalId> {
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance](instance: any): instance is PrincipalClass;
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    covariant(x: any): x is PrincipalId;
    encodeValue(x: PrincipalId): Uint8Array;
    encodeType(): Uint8Array;
    decodeValue(b: Pipe, t: Type): PrincipalId;
    get name(): string;
    valueToString(x: PrincipalId): string;
}
/**
 * The generic type of the arguments of an {@link Func|IDL Function}.
 */
export type GenericIdlFuncArgs = [Type, ...Type[]] | [];
/**
 * The generic type of the return values of an {@link Func|IDL Function}.
 */
export type GenericIdlFuncRets = [Type, ...Type[]] | [];
/**
 * Represents an IDL function reference.
 * @param argTypes Argument types.
 * @param retTypes Return types.
 * @param annotations Function annotations.
 */
export declare class FuncClass<Args extends GenericIdlFuncArgs = GenericIdlFuncArgs, Rets extends GenericIdlFuncRets = GenericIdlFuncRets> extends ConstructType<[PrincipalId, string]> {
    argTypes: Args;
    retTypes: Rets;
    annotations: string[];
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance](instance: any): instance is FuncClass;
    static argsToString(types: Type[], v: any[]): string;
    constructor(argTypes: Args, retTypes: Rets, annotations?: string[]);
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    covariant(x: any): x is [PrincipalId, string];
    encodeValue([principal, methodName]: [PrincipalId, string]): Uint8Array<ArrayBufferLike>;
    _buildTypeTableImpl(T: TypeTable): void;
    decodeValue(b: Pipe, t: Type): [PrincipalId, string];
    get name(): string;
    valueToString([principal, str]: [PrincipalId, string]): string;
    display(): string;
    private encodeAnnotation;
}
/**
 * The generic type of the fields of an {@link Service|IDL Service}.
 */
export type GenericIdlServiceFields = Record<string, FuncClass>;
export declare class ServiceClass<K extends string = string, Fields extends GenericIdlServiceFields = GenericIdlServiceFields> extends ConstructType<PrincipalId> {
    get typeName(): IdlTypeName;
    static [Symbol.hasInstance](instance: any): instance is ServiceClass;
    readonly _fields: Array<[K, Fields[K]]>;
    constructor(fields: Fields);
    accept<D, R>(v: Visitor<D, R>, d: D): R;
    covariant(x: any): x is PrincipalId;
    encodeValue(x: PrincipalId): Uint8Array;
    _buildTypeTableImpl(T: TypeTable): void;
    decodeValue(b: Pipe, t: Type): PrincipalId;
    get name(): string;
    valueToString(x: PrincipalId): string;
    fieldsAsObject(): Fields;
}
/**
 * Encode a array of values
 * @param argTypes - array of Types
 * @param args - array of values
 * @returns {Uint8Array} serialised value
 */
export declare function encode(argTypes: Array<Type<any>>, args: any[]): Uint8Array;
/**
 * Decode a binary value
 * @param retTypes - Types expected in the buffer.
 * @param bytes - hex-encoded string, or buffer.
 * @returns Value deserialised to JS type
 */
export declare function decode(retTypes: Type[], bytes: Uint8Array): JsonValue[];
/**
 * An Interface Factory, normally provided by a Candid code generation.
 */
export type InterfaceFactory = (idl: {
    IDL: {
        Empty: EmptyClass;
        Reserved: ReservedClass;
        Unknown: UnknownClass;
        Bool: BoolClass;
        Null: NullClass;
        Text: TextClass;
        Int: IntClass;
        Nat: NatClass;
        Float32: FloatClass;
        Float64: FloatClass;
        Int8: FixedIntClass;
        Int16: FixedIntClass;
        Int32: FixedIntClass;
        Int64: FixedIntClass;
        Nat8: FixedNatClass;
        Nat16: FixedNatClass;
        Nat32: FixedNatClass;
        Nat64: FixedNatClass;
        Principal: PrincipalClass;
        Tuple: typeof Tuple;
        Vec: typeof Vec;
        Opt: typeof Opt;
        Record: typeof Record;
        Variant: typeof Variant;
        Rec: typeof Rec;
        Func: typeof Func;
        Service(t: Record<string, FuncClass>): ServiceClass;
    };
}) => ServiceClass;
export declare const Empty: EmptyClass;
export declare const Reserved: ReservedClass;
/**
 * Client-only type for deserializing unknown data. Not supported by Candid, and its use is discouraged.
 */
export declare const Unknown: UnknownClass;
export declare const Bool: BoolClass;
export declare const Null: NullClass;
export declare const Text: TextClass;
export declare const Int: IntClass;
export declare const Nat: NatClass;
export declare const Float32: FloatClass;
export declare const Float64: FloatClass;
export declare const Int8: FixedIntClass;
export declare const Int16: FixedIntClass;
export declare const Int32: FixedIntClass;
export declare const Int64: FixedIntClass;
export declare const Nat8: FixedNatClass;
export declare const Nat16: FixedNatClass;
export declare const Nat32: FixedNatClass;
export declare const Nat64: FixedNatClass;
export declare const Principal: PrincipalClass;
/**
 *
 * @param types array of any types
 * @returns TupleClass from those types
 */
export declare function Tuple<T extends any[]>(...types: T): TupleClass<T>;
/**
 *
 * @param t IDL Type
 * @returns VecClass from that type
 */
export declare function Vec<T>(t: Type<T>): VecClass<T>;
/**
 *
 * @param t IDL Type
 * @returns OptClass of Type
 */
export declare function Opt<T>(t: Type<T>): OptClass<T>;
/**
 *
 * @param t Record of string and IDL Type
 * @returns RecordClass of string and Type
 */
export declare function Record(t: Record<string, Type>): RecordClass;
/**
 *
 * @param fields Record of string and IDL Type
 * @returns VariantClass
 */
export declare function Variant(fields: Record<string, Type>): VariantClass;
/**
 *
 * @returns new RecClass
 */
export declare function Rec(): RecClass;
/**
 *
 * @param args array of IDL Types
 * @param ret array of IDL Types
 * @param annotations array of strings, [] by default
 * @returns new FuncClass
 */
export declare function Func<Args extends GenericIdlFuncArgs = GenericIdlFuncArgs, Ret extends GenericIdlFuncRets = GenericIdlFuncRets>(args: Args, ret: Ret, annotations?: string[]): FuncClass<Args, Ret>;
/**
 *
 * @param t Record of string and FuncClass
 * @returns ServiceClass
 */
export declare function Service<K extends string = string, Fields extends GenericIdlServiceFields = GenericIdlServiceFields>(t: Fields): ServiceClass<K, Fields>;
/** Resets the global subtyping cache */
export declare function resetSubtypeCache(): void;
/**
 * Subtyping on Candid types t1 <: t2 (Exported for testing)
 * @param t1 The potential subtype
 * @param t2 The potential supertype
 */
export declare function subtype(t1: Type, t2: Type): boolean;
export {};
//# sourceMappingURL=idl.d.ts.map