@lifi/composer-sdk
Version:
Public Composer SDK for building and submitting flows
120 lines • 6.45 kB
text/typescript
import { OutputKind, TypedLiteral, TypedRef } from "../types.cjs";
import { BindValue, Ref, Resource, SolType, StaticSolType } from "@lifi/compose-spec";
//#region src/authoring/handles.d.ts
/**
* A handle referencing a flow input declared in the flow's input schema.
* The phantom `__outputKind` field carries the type parameter through
* TypeScript's structural type system without affecting runtime shape.
*/
export interface InputHandle<T extends OutputKind = OutputKind> {
readonly _tag: "input";
readonly inputName: string;
readonly __outputKind?: T;
}
/**
* An input handle for a resource (token) input, carrying the resource
* declaration alongside the reference.
*/
export interface ResourceInputHandle extends InputHandle<"resource"> {
readonly resource: Resource;
}
/**
* A handle referencing an output port of a previously declared operation node.
* The phantom `__outputKind` field carries the type parameter through
* TypeScript's structural type system without affecting runtime shape.
*/
export interface OutputHandle<T extends OutputKind = OutputKind> {
readonly _tag: "output";
readonly nodeId: string;
readonly portName: string;
readonly __outputKind?: T;
}
/**
* What an output family's sizing parameter accepts, given the config field the
* family counts from: an array of that field's elements, or a number.
*/
export type FamilySource<Field> = Field extends readonly (infer E)[] ? readonly E[] : number;
/** Whether a number literal is a valid family count: a non-negative integer. */
type IsCountLiteral<N extends number> = `${N}` extends `-${string}` | `${string}.${string}` | `${string}e${string}` ? false : true;
/**
* `N` resource handles as a tuple. A non-literal `number`, or a literal that is
* not a valid count, gives an open array; {@link FamilyCount} rejects the
* invalid literal at the call site.
*/
type HandleTuple<N extends number, Acc extends readonly OutputHandle<"resource">[] = readonly []> = number extends N ? readonly OutputHandle<"resource">[] : IsCountLiteral<N> extends false ? readonly OutputHandle<"resource">[] : Acc["length"] extends N ? Acc : HandleTuple<N, readonly [...Acc, OutputHandle<"resource">]>;
/**
* The handles of an output family: one resource {@link OutputHandle} per
* element of the config array the family counts from, or as many as the config
* count. A literal array or count yields a tuple of that length, so indexing
* past the last instance is a type error.
*/
export type OutputFamilyHandles<TCount extends readonly unknown[] | number> = TCount extends readonly unknown[] ? { readonly [I in keyof TCount]: OutputHandle<"resource">; } : TCount extends number ? HandleTuple<TCount> : never;
/**
* Holds the config value an output family counts from to the op's own type. A
* runtime-sized array or count passes as is. A literal tuple must also satisfy
* `Shape`, so a tuple shorter than the op's `minItems` fails at the call site
* instead of at the server's bind step. A literal count must be a non-negative
* integer.
*/
export type FamilyCount<TCount extends readonly unknown[] | number, Shape> = TCount extends readonly unknown[] ? number extends TCount["length"] ? unknown : TCount extends Shape ? unknown : {
readonly "output family config array has too few entries": never;
} : TCount extends number ? IsCountLiteral<TCount> extends true ? unknown : {
readonly "output family count must be a non-negative integer": never;
} : unknown;
/** Discriminated union of all handle types that can be bound to operation arguments. */
export type AnyHandle = InputHandle | OutputHandle;
/** Type guard that narrows an {@link AnyHandle} to an {@link InputHandle}. */
export declare const isInputHandle: (h: AnyHandle) => h is InputHandle;
/** Type guard that narrows an {@link AnyHandle} to an {@link OutputHandle}. */
export declare const isOutputHandle: (h: AnyHandle) => h is OutputHandle;
/**
* Converts a handle to a JSON `$ref` pointer used in the flow document.
* Input handles become `"input.<name>"`; output handles become `"<nodeId>.<port>"`.
*/
export declare const handleToRef: (h: AnyHandle) => {
$ref: string;
};
/**
* For a bind slot expecting type T, widen the set of accepted handle types:
* - `'bytes32'` is the raw 32-byte word type: accept any static-32-byte handle
* (`uint256`/`uintN`/`address`/`bool`/`bytes32`) plus `'resource'` (a uint256
* amount). At the IR1 boundary every value is a type-erased word, so any
* static-32-byte handle is a sound bind for a `bytes32` payload port.
* - `'uint256'` keeps its existing widening to also accept `'resource'`-tagged
* handles (resources are uint256 amounts).
* - every other type keeps exact-SolType matching.
*/
type SlotAssignable<T extends OutputKind> = T extends "bytes32" ? StaticSolType | "resource" : T extends "uint256" ? T | "resource" : T;
/**
* The values accepted by a typed slot that must resolve to a `$ref`:
* - `OutputHandle<T>` / `InputHandle<T>` (same type)
* - For `'uint256'` slots, also `'resource'`-tagged handles
* - For `'bytes32'` slots, any static-32-byte handle (and `'resource'`)
* - `TypedRef<T>` (typed context refs, subject to `SlotAssignable`)
*
* Plain `{ $ref: '...' }` objects are **not** accepted - use `raw.ref<T>()`
* to create a typed ref when you need to reference a raw path.
*/
export type RefBindable<T extends OutputKind> = OutputHandle<SlotAssignable<T>> | InputHandle<SlotAssignable<T>> | TypedRef<SlotAssignable<T>>;
/**
* Any ref-resolving bindable, with no per-slot type constraint.
*/
export type AnyRefBindable = InputHandle | OutputHandle | TypedRef;
/**
* The set of values accepted by a typed operation bind slot: everything
* {@link RefBindable} accepts, plus a {@link TypedLiteral} constant baked
* into the flow document. A `'resource'` slot rejects a literal: a token
* resource is not a scalar constant.
*
* Use `raw.literal<T>()` to create one.
*/
export type Bindable<T extends OutputKind> = RefBindable<T> | LiteralBindable<SlotAssignable<T>>;
type LiteralBindable<K extends OutputKind> = K extends SolType ? TypedLiteral<K> : never;
/**
* Converts a bindable to the wire `bind` value it denotes: handles become
* `$ref` pointers, refs and literals pass through as-is.
*/
export declare const toBindValue: (bindable: InputHandle | OutputHandle | TypedRef | TypedLiteral | Ref) => BindValue;
//#endregion
export {};
//# sourceMappingURL=handles.d.cts.map