Add ExtractFlowLeafSteps and ExtractFlowOutput utility types to DSL (#92)

* feat: add utility type ExtractFlowLeafSteps to extract leaf steps from a Flow

- Introduced ExtractFlowLeafSteps type in dsl.ts for extracting steps that are not dependencies
of others
- Added comprehensive tests for ExtractFlowLeafSteps covering various flow configurations
- Enhanced type safety and clarity in flow step dependency analysis

* feat: add type extraction utility for Flow objects

Introduce ExtractFlowOutput type to extract step output types from Flow instances,
along with corresponding tests to ensure correct type inference for various flow
structures, including empty flows, single-step flows, multiple steps, and complex
dependency chains.
Also update dsl.ts to include the new ExtractFlowOutput type.

* chore: update .gitignore to exclude local Claude settings file

* test: update type assertion for empty flow output in extract-flow-output tests

Refactor test to use a type alias instead of creating an unused flow instance, and
adjust expected type to Record<string, never> for clarity and correctness.

* feat: add utility types ExtractFlowLeafSteps and ExtractFlowOutput

- Introduced new utility types for flow extraction in '@pgflow/dsl' module

Author: jumski

.changeset/eleven-icons-think.md

@@ -0,0 +1,5 @@
+---
+'@pgflow/dsl': patch
+---
+
+Added ExtractFlowLeafSteps and ExtractFlowOutput utility types

.gitignore

@@ -49,3 +49,5 @@ tsconfig.vitest-temp.json
 deno-dist/
 .nx-inputs
 .vscode
+
+**/.claude/settings.local.json

pkgs/dsl/__tests__/types/extract-flow-leaf-steps.test-d.ts

@@ -0,0 +1,118 @@
+import { ExtractFlowLeafSteps, Flow } from '../../src/index.js';
+import { describe, it, expectTypeOf } from 'vitest';
+
+describe('ExtractFlowLeafSteps utility type', () => {
+  it('should return never for a flow without steps', () => {
+    const emptyFlow = new Flow({ slug: 'empty_flow' });
+
+    type LeafSteps = ExtractFlowLeafSteps<typeof emptyFlow>;
+
+    // A flow without steps should have no leaf steps
+    expectTypeOf<LeafSteps>().toEqualTypeOf({});
+    expectTypeOf<keyof LeafSteps>().toEqualTypeOf<never>();
+  });
+
+  it('should correctly extract a single leaf step', () => {
+    const singleStepFlow = new Flow<{ input: string }>({
+      slug: 'single_step_flow',
+    }).step({ slug: 'process' }, (input) => ({
+      result: input.run.input.toUpperCase(),
+    }));
+
+    type LeafSteps = ExtractFlowLeafSteps<typeof singleStepFlow>;
+
+    // The only step is a leaf step since no other step depends on it
+    expectTypeOf<LeafSteps>().toMatchTypeOf<{
+      process: { result: string };
+    }>();
+
+    // Ensure it doesn't include non-existent steps
+    expectTypeOf<LeafSteps>().not.toMatchTypeOf<{
+      nonExistentStep: unknown;
+    }>();
+  });
+
+  it('should correctly extract multiple leaf steps', () => {
+    const multiLeafFlow = new Flow<{ data: number }>({
+      slug: 'multi_leaf_flow',
+    })
+      .step({ slug: 'intermediate' }, (input) => ({
+        value: input.run.data * 2,
+      }))
+      .step({ slug: 'leaf1', dependsOn: ['intermediate'] }, (input) => ({
+        squared: input.intermediate.value ** 2,
+      }))
+      .step({ slug: 'leaf2', dependsOn: ['intermediate'] }, (input) => ({
+        doubled: input.intermediate.value * 2,
+      }));
+
+    type LeafSteps = ExtractFlowLeafSteps<typeof multiLeafFlow>;
+
+    // Both leaf1 and leaf2 are leaf steps since no other steps depend on them
+    expectTypeOf<LeafSteps>().toMatchTypeOf<{
+      leaf1: { squared: number };
+      leaf2: { doubled: number };
+    }>();
+
+    // The intermediate step should not be included as it's a dependency
+    expectTypeOf<LeafSteps>().not.toMatchTypeOf<{
+      intermediate: { value: number };
+    }>();
+  });
+
+  it('should correctly identify a root step that is also a leaf step', () => {
+    const rootLeafFlow = new Flow<{ input: string }>({ slug: 'root_leaf_flow' })
+      .step({ slug: 'rootLeaf' }, (input) => ({
+        processed: input.run.input.trim(),
+      }))
+      .step({ slug: 'intermediate' }, (input) => ({
+        length: input.run.input.length,
+      }))
+      .step({ slug: 'dependent', dependsOn: ['intermediate'] }, (input) => ({
+        result: input.intermediate.length > 10,
+      }));
+
+    type LeafSteps = ExtractFlowLeafSteps<typeof rootLeafFlow>;
+
+    // rootLeaf is both a root step (no dependencies) and a leaf step (no dependents)
+    // dependent is a leaf step (no dependents)
+    expectTypeOf<LeafSteps>().toMatchTypeOf<{
+      rootLeaf: { processed: string };
+      dependent: { result: boolean };
+    }>();
+
+    // intermediate should not be included as it's a dependency
+    expectTypeOf<LeafSteps>().not.toMatchTypeOf<{
+      intermediate: { length: number };
+    }>();
+  });
+
+  it('should handle complex dependency chains', () => {
+    const complexFlow = new Flow<{ input: number }>({ slug: 'complex_flow' })
+      .step({ slug: 'step1' }, (input) => ({ value: input.run.input + 1 }))
+      .step({ slug: 'step2', dependsOn: ['step1'] }, (input) => ({
+        value: input.step1.value * 2,
+      }))
+      .step({ slug: 'step3', dependsOn: ['step1'] }, (input) => ({
+        value: input.step1.value - 1,
+      }))
+      .step({ slug: 'step4', dependsOn: ['step2', 'step3'] }, (input) => ({
+        sum: input.step2.value + input.step3.value,
+        original: input.run.input,
+      }));
+
+    type LeafSteps = ExtractFlowLeafSteps<typeof complexFlow>;
+
+    // Only step4 is a leaf step as it's not a dependency of any other step
+    expectTypeOf<LeafSteps>().toMatchTypeOf<{
+      step4: { sum: number; original: number };
+    }>();
+
+    // None of the intermediate steps should be included
+    expectTypeOf<LeafSteps>().not.toMatchTypeOf<{
+      step1: unknown;
+      step2: unknown;
+      step3: unknown;
+    }>();
+  });
+});

pkgs/dsl/__tests__/types/extract-flow-output.test-d.ts

@@ -0,0 +1,132 @@
+import { ExtractFlowOutput, StepOutput, Flow } from '../../src/index.js';
+import { describe, it, expectTypeOf } from 'vitest';
+
+describe('ExtractFlowOutput utility type', () => {
+  it('should return an empty object for a flow without steps', () => {
+    // Use type only instead of creating an unused variable
+    type EmptyFlow = Flow<unknown>;
+    type FlowOutput = ExtractFlowOutput<EmptyFlow>;
+
+    // For an empty flow, output is an empty object
+    expectTypeOf<FlowOutput>().toEqualTypeOf<Record<string, never>>();
+    expectTypeOf<keyof FlowOutput>().toEqualTypeOf<never>();
+  });
+
+  it('should correctly output for a flow with a single leaf step', () => {
+    const singleStepFlow = new Flow<{ input: string }>({
+      slug: 'single_step_flow',
+    }).step({ slug: 'process' }, (input) => ({
+      result: input.run.input.toUpperCase(),
+    }));
+
+    type FlowOutput = ExtractFlowOutput<typeof singleStepFlow>;
+
+    // The only leaf step is "process", whose output type is StepOutput<typeof singleStepFlow, 'process'>
+    expectTypeOf<FlowOutput>().toMatchTypeOf<{
+      process: StepOutput<typeof singleStepFlow, 'process'>;
+    }>();
+
+    // The value for process in output should match its StepOutput type
+    expectTypeOf<FlowOutput['process']>().toEqualTypeOf<{ result: string }>();
+
+    // FlowOutput should not have other keys
+    expectTypeOf<FlowOutput>().not.toMatchTypeOf<{
+      nonExistentStep: unknown;
+    }>();
+  });
+
+  it('should correctly output for multiple leaf steps', () => {
+    const multiLeafFlow = new Flow<{ data: number }>({
+      slug: 'multi_leaf_flow',
+    })
+      .step({ slug: 'intermediate' }, (input) => ({
+        value: input.run.data * 2,
+      }))
+      .step({ slug: 'leaf1', dependsOn: ['intermediate'] }, (input) => ({
+        squared: input.intermediate.value ** 2,
+      }))
+      .step({ slug: 'leaf2', dependsOn: ['intermediate'] }, (input) => ({
+        doubled: input.intermediate.value * 2,
+      }));
+
+    type FlowOutput = ExtractFlowOutput<typeof multiLeafFlow>;
+
+    // FlowOutput should have exactly leaf1 and leaf2, each with their respective StepOutputs
+    expectTypeOf<FlowOutput>().toMatchTypeOf<{
+      leaf1: StepOutput<typeof multiLeafFlow, 'leaf1'>;
+      leaf2: StepOutput<typeof multiLeafFlow, 'leaf2'>;
+    }>();
+
+    expectTypeOf<FlowOutput['leaf1']>().toEqualTypeOf<{ squared: number }>();
+    expectTypeOf<FlowOutput['leaf2']>().toEqualTypeOf<{ doubled: number }>();
+
+    // Should NOT have intermediate
+    expectTypeOf<FlowOutput>().not.toMatchTypeOf<{
+      intermediate: unknown;
+    }>();
+  });
+
+  it('should correctly handle a root step that is also a leaf step', () => {
+    const rootLeafFlow = new Flow<{ input: string }>({ slug: 'root_leaf_flow' })
+      .step({ slug: 'rootLeaf' }, (input) => ({
+        processed: input.run.input.trim(),
+      }))
+      .step({ slug: 'intermediate' }, (input) => ({
+        length: input.run.input.length,
+      }))
+      .step({ slug: 'dependent', dependsOn: ['intermediate'] }, (input) => ({
+        result: input.intermediate.length > 10,
+      }));
+
+    type FlowOutput = ExtractFlowOutput<typeof rootLeafFlow>;
+
+    expectTypeOf<FlowOutput>().toMatchTypeOf<{
+      rootLeaf: StepOutput<typeof rootLeafFlow, 'rootLeaf'>;
+      dependent: StepOutput<typeof rootLeafFlow, 'dependent'>;
+    }>();
+
+    expectTypeOf<FlowOutput['rootLeaf']>().toEqualTypeOf<{
+      processed: string;
+    }>();
+    expectTypeOf<FlowOutput['dependent']>().toEqualTypeOf<{
+      result: boolean;
+    }>();
+
+    expectTypeOf<FlowOutput>().not.toMatchTypeOf<{
+      intermediate: unknown;
+    }>();
+  });
+
+  it('should handle complex dependency chains', () => {
+    const complexFlow = new Flow<{ input: number }>({ slug: 'complex_flow' })
+      .step({ slug: 'step1' }, (input) => ({ value: input.run.input + 1 }))
+      .step({ slug: 'step2', dependsOn: ['step1'] }, (input) => ({
+        value: input.step1.value * 2,
+      }))
+      .step({ slug: 'step3', dependsOn: ['step1'] }, (input) => ({
+        value: input.step1.value - 1,
+      }))
+      .step({ slug: 'step4', dependsOn: ['step2', 'step3'] }, (input) => ({
+        sum: input.step2.value + input.step3.value,
+        original: input.run.input,
+      }));
+
+    type FlowOutput = ExtractFlowOutput<typeof complexFlow>;
+
+    expectTypeOf<FlowOutput>().toMatchTypeOf<{
+      step4: StepOutput<typeof complexFlow, 'step4'>;
+    }>();
+
+    expectTypeOf<FlowOutput['step4']>().toEqualTypeOf<{
+      sum: number;
+      original: number;
+    }>();
+
+    // No extras
+    expectTypeOf<FlowOutput>().not.toMatchTypeOf<{
+      step1: unknown;
+      step2: unknown;
+      step3: unknown;
+    }>();
+  });
+});

pkgs/dsl/src/dsl.ts

@@ -65,6 +65,22 @@ export type ExtractFlowInput<TFlow extends AnyFlow> = TFlow extends Flow<
   ? TI
   : never;
 
+/**
+ * Extracts the output type from a Flow
+ * @template TFlow - The Flow type to extract from
+ */
+export type ExtractFlowOutput<TFlow extends AnyFlow> = TFlow extends Flow<
+  infer _TI,
+  infer _TS,
+  infer _TD
+>
+  ? {
+      [K in keyof ExtractFlowLeafSteps<TFlow> as K extends string
+        ? K
+        : never]: StepOutput<TFlow, K & string>;
+    }
+  : never;
+
 /**
  * Extracts the steps type from a Flow
  * @template TFlow - The Flow type to extract from
@@ -100,6 +116,18 @@ type StepDepsOf<
   ? ExtractFlowDeps<TFlow>[TStepSlug][number] // The string slugs that TStepSlug depends on
   : never;
 
+/**
+ * Extracts only the leaf steps from a Flow (steps that are not dependencies of any other steps)
+ * @template TFlow - The Flow type to extract from
+ */
+export type ExtractFlowLeafSteps<TFlow extends AnyFlow> = {
+  [K in keyof ExtractFlowSteps<TFlow> as K extends string
+    ? K extends ExtractFlowDeps<TFlow>[keyof ExtractFlowDeps<TFlow>][number]
+      ? never
+      : K
+    : never]: ExtractFlowSteps<TFlow>[K];
+};
+
 // Utility type to extract the output type of a step handler from a Flow
 // Usage:
 //   StepOutput<typeof flow, 'step1'>