@lifi/composer-sdk 0.6.2 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/composer-sdk",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Public Composer SDK for building and submitting flows",
   "license": "Apache-2.0",
   "repository": {
@@ -47,16 +47,17 @@
     "example:staged": "tsx src/examples/run.ts --staged"
   },
   "peerDependencies": {
-    "@lifi/compose-spec": "0.6.2"
+    "@lifi/compose-spec": "0.7.0"
   },
   "dependencies": {
     "abitype": "^1.2.3",
     "effect": "^3.21.0",
-    "zod": "^4.1.11"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "@eslint/compat": "^1.4.0",
     "@lifi/compose-spec": "workspace:^",
+    "@lifi/vitest-config": "workspace:^",
     "@types/node": "^25.6.0",
     "@typescript-eslint/eslint-plugin": "^8.68.0",
     "@typescript-eslint/parser": "^8.68.0",

package/src/authoring/FlowBuilderCore.ts

@@ -1,12 +1,14 @@
-import type {
-  AppliedGuard,
-  BindValue,
-  Call,
-  Flow,
-  FlowInput,
-  Ref,
-  Resource,
-  SolType,
+import {
+  type AppliedGuard,
+  type BindValue,
+  type Call,
+  familySize,
+  type Flow,
+  type FlowInput,
+  instancePortName,
+  type Ref,
+  type Resource,
+  type SolType,
 } from '@lifi/compose-spec';
 
 import type {
@@ -146,16 +148,34 @@ export interface FlowBuilderCore<T extends InputSchema = InputSchema> {
 /** Maps output port names to their output kind for compile-time and runtime validation. */
 export type OutputSpec = Record<string, OutputKind>;
 
+/**
+ * Maps each output family's port name to the config key that sizes it: an
+ * array (one instance per element) or a non-negative integer count.
+ * A family port is also listed in the {@link OutputSpec}, as `'resource'`.
+ */
+export type FamilySpec = Readonly<Record<string, string>>;
+
+/** The handles `call` returns for an {@link OutputSpec} and its families. */
+export type OutputHandles<O extends OutputSpec, F extends FamilySpec> = {
+  readonly [K in keyof O & string]: K extends keyof F
+    ? readonly OutputHandle<'resource'>[]
+    : OutputHandle<O[K]>;
+};
+
 /** Internal interface exposed to bindGeneratedOps — not part of the public API. */
 export interface FlowBuilderInternal<
   T extends InputSchema = InputSchema,
 > extends FlowBuilderCore<T> {
-  readonly call: <O extends OutputSpec>(
+  readonly call: <
+    O extends OutputSpec,
+    F extends FamilySpec = Record<never, string>,
+  >(
     nodeId: string,
     op: string,
     args: CallArgs,
     outputs: O,
-  ) => { readonly [K in keyof O & string]: OutputHandle<O[K]> };
+    families?: F,
+  ) => OutputHandles<O, F>;
 }
 
 const isResource = (decl: InputDecl): decl is Resource =>
@@ -194,12 +214,16 @@ export const createFlowBuilderCore = <T extends InputSchema>(
     }
   }
 
-  const call = <O extends OutputSpec>(
+  const call = <
+    O extends OutputSpec,
+    F extends FamilySpec = Record<never, string>,
+  >(
     nodeId: string,
     op: string,
     args: CallArgs,
     outputs: O,
-  ): { readonly [K in keyof O & string]: OutputHandle<O[K]> } => {
+    families?: F,
+  ): OutputHandles<O, F> => {
     if (nodeIds.has(nodeId)) throw new Error(`Duplicate node id: "${nodeId}"`);
     nodeIds.add(nodeId);
 
@@ -208,18 +232,26 @@ export const createFlowBuilderCore = <T extends InputSchema>(
       bind[key] = toBindValue(val);
     }
 
+    const config = (args.config ?? {}) as Record<string, unknown>;
     const node: Call = {
       id: nodeId,
       op,
       bind,
-      config: (args.config ?? {}) as Record<string, unknown>,
+      config,
       ...(args.guards && args.guards.length > 0 && { guards: args.guards }),
     };
     nodes.push(node);
 
-    type Result = { readonly [K in keyof O & string]: OutputHandle<O[K]> };
-    return new Proxy({} as Result, {
-      get: (_target, prop): OutputHandle | undefined => {
+    const outputHandle = (portName: string): OutputHandle => ({
+      _tag: 'output',
+      nodeId,
+      portName,
+    });
+    return new Proxy({} as OutputHandles<O, F>, {
+      get: (
+        _target,
+        prop,
+      ): OutputHandle | readonly OutputHandle[] | undefined => {
         if (typeof prop !== 'string' || prop === 'then') return undefined;
         if (!(prop in outputs)) {
           throw new Error(
@@ -228,7 +260,12 @@ export const createFlowBuilderCore = <T extends InputSchema>(
             ).join(', ')}`,
           );
         }
-        return { _tag: 'output', nodeId, portName: prop };
+        const countFrom = families?.[prop];
+        if (countFrom === undefined) return outputHandle(prop);
+        const size = familySize({ name: prop, countFrom }, config);
+        return Array.from({ length: size }, (_, index) =>
+          outputHandle(instancePortName(prop, index)),
+        );
       },
     });
   };

package/src/authoring/handles.ts

@@ -39,6 +39,73 @@ export interface OutputHandle<T extends OutputKind = OutputKind> {
   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;
 

package/src/examples/splitAndZap.ts

@@ -18,8 +18,8 @@ const STEAKHOUSE_USDC = '0xBEEF01735c132Ada46AA9aA4c54623cAA92A64CB';
  * Split USDC 60/40 and zap each portion into a different vault.
  *
  * Demonstrates:
- * - core.split to divide a resource by basis-point ratio
- * - Threading split outputs into two independent lifi.zap nodes
+ * - core.partition to divide a resource into one part per basis-point share
+ * - Destructuring the typed `parts` tuple into two independent lifi.zap nodes
  * - Slippage guards on both zap outputs
  */
 export const buildSplitAndZapExample = (): {
@@ -35,15 +35,16 @@ export const buildSplitAndZapExample = (): {
     },
   });
 
-  // Split USDC 60/40 — 6000 bps to `a`, remainder to `b`.
-  const { a, b } = builder.core.split('split', {
+  // Partition USDC 60/40 — one part per `bps` entry. Every part but the last
+  // is rounded down; the last takes the remainder.
+  const [toAave, toMorpho] = builder.core.partition('split', {
     bind: { source: builder.inputs.amountIn },
-    config: { bps: 6000 },
-  });
+    config: { bps: [6000, 4000] },
+  }).parts;
 
   // Zap 60% into Aave v3 aEthUSDC.
   builder.lifi.zap('zap-aave', {
-    bind: { amountIn: a },
+    bind: { amountIn: toAave },
     config: {
       resourceOut: resources.erc20(A_ETH_USDC, 1),
     },
@@ -52,7 +53,7 @@ export const buildSplitAndZapExample = (): {
 
   // Zap 40% into Steakhouse USDC (Morpho).
   builder.lifi.zap('zap-morpho', {
-    bind: { amountIn: b },
+    bind: { amountIn: toMorpho },
     config: {
       resourceOut: resources.erc20(STEAKHOUSE_USDC, 1),
     },