Enforce JSON-safe step outputs without narrowing inference

Author: jumski

.changeset/enforce-json-step-outputs.md

@@ -0,0 +1,5 @@
+---
+'@pgflow/dsl': patch
+---
+
+Enforce JSON-compatible step outputs at .step() construction time

.changeset/extract-flow-output-skippable-keys-3570.md

@@ -0,0 +1,6 @@
+---
+'@pgflow/dsl': patch
+'@pgflow/edge-worker': patch
+---
+
+Make skippable leaf step keys optional in ExtractFlowOutput type

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

@@ -112,13 +112,16 @@ describe('ExtractFlowOutput utility type', () => {
       .step({ slug: 'step3', dependsOn: ['step1'] }, (deps) => ({
         value: deps.step1.value - 1,
       }))
-      .step({ slug: 'step4', dependsOn: ['step2', 'step3'] }, async (deps, ctx) => {
-        const flowInput = await ctx.flowInput;
-        return {
-          sum: deps.step2.value + deps.step3.value,
-          original: flowInput.input,
-        };
-      });
+      .step(
+        { slug: 'step4', dependsOn: ['step2', 'step3'] },
+        async (deps, ctx) => {
+          const flowInput = await ctx.flowInput;
+          return {
+            sum: deps.step2.value + deps.step3.value,
+            original: flowInput.input,
+          };
+        }
+      );
 
     type FlowOutput = ExtractFlowOutput<typeof complexFlow>;
 
@@ -138,4 +141,79 @@ describe('ExtractFlowOutput utility type', () => {
       step3: unknown;
     }>();
   });
+
+  it('makes skippable leaf steps optional in flow output', () => {
+    const skippableLeafFlow = new Flow<{ input: string }>({
+      slug: 'skippable_leaf_flow',
+    })
+      .step({ slug: 'prepare' }, (flowInput) => ({ text: flowInput.input }))
+      .step(
+        {
+          slug: 'leaf_optional',
+          dependsOn: ['prepare'],
+          if: { prepare: { text: 'run' } },
+          whenUnmet: 'skip',
+        },
+        (deps) => ({ value: deps.prepare.text.toUpperCase() })
+      );
+
+    type FlowOutput = ExtractFlowOutput<typeof skippableLeafFlow>;
+
+    expectTypeOf<FlowOutput>().toMatchTypeOf<{
+      leaf_optional?: StepOutput<typeof skippableLeafFlow, 'leaf_optional'>;
+    }>();
+
+    expectTypeOf<{
+      leaf_optional?: StepOutput<typeof skippableLeafFlow, 'leaf_optional'>;
+    }>().toMatchTypeOf<FlowOutput>();
+  });
+
+  it('keeps non-skippable leaf steps required in flow output', () => {
+    const requiredLeafFlow = new Flow<{ input: string }>({
+      slug: 'required_leaf_flow',
+    }).step({ slug: 'leaf_required' }, (flowInput) => ({
+      value: flowInput.input.length,
+    }));
+
+    type FlowOutput = ExtractFlowOutput<typeof requiredLeafFlow>;
+
+    expectTypeOf<FlowOutput>().toMatchTypeOf<{
+      leaf_required: StepOutput<typeof requiredLeafFlow, 'leaf_required'>;
+    }>();
+
+    expectTypeOf<{
+      leaf_required: StepOutput<typeof requiredLeafFlow, 'leaf_required'>;
+    }>().toMatchTypeOf<FlowOutput>();
+  });
+
+  it('supports mixed required and skippable leaf outputs', () => {
+    const mixedLeafFlow = new Flow<{ input: string }>({
+      slug: 'mixed_leaf_flow',
+    })
+      .step({ slug: 'prepare' }, (flowInput) => ({ text: flowInput.input }))
+      .step({ slug: 'required_leaf', dependsOn: ['prepare'] }, (deps) => ({
+        value: deps.prepare.text.length,
+      }))
+      .step(
+        {
+          slug: 'optional_leaf',
+          dependsOn: ['prepare'],
+          if: { prepare: { text: 'run' } },
+          whenUnmet: 'skip-cascade',
+        },
+        (deps) => ({ value: deps.prepare.text.toUpperCase() })
+      );
+
+    type FlowOutput = ExtractFlowOutput<typeof mixedLeafFlow>;
+
+    expectTypeOf<FlowOutput>().toMatchTypeOf<{
+      required_leaf: StepOutput<typeof mixedLeafFlow, 'required_leaf'>;
+      optional_leaf?: StepOutput<typeof mixedLeafFlow, 'optional_leaf'>;
+    }>();
+
+    expectTypeOf<{
+      required_leaf: StepOutput<typeof mixedLeafFlow, 'required_leaf'>;
+      optional_leaf?: StepOutput<typeof mixedLeafFlow, 'optional_leaf'>;
+    }>().toMatchTypeOf<FlowOutput>();
+  });
 });

pkgs/dsl/__tests__/types/step-interface-output.test-d.ts

@@ -0,0 +1,38 @@
+import { Flow } from '../../src/index.js';
+import { describe, expectTypeOf, it } from 'vitest';
+
+interface FinalizeContextOutput {
+  sessionId: string;
+  sonioxTranscriptionId: string;
+  isTerminal: boolean;
+}
+
+describe('.step() supports interface DTO outputs', () => {
+  it('keeps dependent step input precise for interface-based output', () => {
+    new Flow<{ id: string }>({ slug: 'interface-output-flow' })
+      .step({ slug: 'finalizeContext' }, async () => {
+        const result: FinalizeContextOutput = {
+          sessionId: 's1',
+          sonioxTranscriptionId: 't1',
+          isTerminal: false,
+        };
+
+        return result;
+      })
+      .step(
+        {
+          slug: 'next',
+          dependsOn: ['finalizeContext'],
+          if: { finalizeContext: { isTerminal: false } },
+        },
+        (deps) => {
+          expectTypeOf(deps.finalizeContext.sessionId).toEqualTypeOf<string>();
+          expectTypeOf(
+            deps.finalizeContext.sonioxTranscriptionId
+          ).toEqualTypeOf<string>();
+
+          return { ok: true };
+        }
+      );
+  });
+});

pkgs/dsl/__tests__/types/step-method-json-output.test-d.ts

@@ -0,0 +1,72 @@
+import { Flow, type StepOutput } from '../../src/index.js';
+import { describe, expectTypeOf, it } from 'vitest';
+
+interface InterfaceJsonDto {
+  sessionId: string;
+  isTerminal: boolean;
+}
+
+describe('.step() JSON output constraints', () => {
+  it('accepts JSON-compatible step outputs', () => {
+    new Flow<{ x: string }>({ slug: 'test' })
+      .step({ slug: 'valid1' }, () => ({ ok: true }))
+      .step({ slug: 'valid2' }, () => ({ maybe: null as string | null }))
+      .step({ slug: 'valid3' }, () => ['a', 'b', 'c'])
+      .step({ slug: 'valid4' }, () => null)
+      .step({ slug: 'valid5' }, () => 123)
+      .step({ slug: 'valid6' }, () => {
+        const dto: InterfaceJsonDto = {
+          sessionId: 's1',
+          isTerminal: false,
+        };
+
+        return dto;
+      })
+      .step({ slug: 'valid7' }, (): { entryId?: string } => ({
+        entryId: 'entry-1',
+      }))
+      .step({ slug: 'valid8' }, (): { entryId?: string } => ({}))
+      // implied optional via inferred branch return (not explicit annotation)
+      .step({ slug: 'valid9' }, () =>
+        Math.random() > 0.5 ? { entryId: 'entry-1' } : {}
+      );
+  });
+
+  it('preserves widened output inference for step outputs', () => {
+    const flow = new Flow<{ x: string }>({ slug: 'test_widened' }).step(
+      { slug: 'numberStep' },
+      () => 123
+    );
+
+    expectTypeOf<
+      StepOutput<typeof flow, 'numberStep'>
+    >().toEqualTypeOf<number>();
+  });
+
+  it('rejects undefined in step outputs', () => {
+    new Flow<{ x: string }>({ slug: 'test_invalid' })
+      // @ts-expect-error - undefined is not Json
+      .step({ slug: 'invalid1' }, () => undefined)
+      // @ts-expect-error - property type includes undefined (not Json)
+      .step({ slug: 'invalid2' }, () => ({
+        ok: true,
+        maybe: undefined as string | undefined,
+      }))
+      // @ts-expect-error - implied branch includes explicit undefined value
+      .step({ slug: 'invalid5' }, () =>
+        Math.random() > 0.5 ? { entryId: 'entry-1' } : { entryId: undefined }
+      )
+      // @ts-expect-error - top-level undefined branch is not Json
+      .step({ slug: 'invalid6' }, () =>
+        Math.random() > 0.5 ? { entryId: 'entry-1' } : undefined
+      );
+  });
+
+  it('rejects other non-JSON output types', () => {
+    new Flow<{ x: string }>({ slug: 'test_invalid_other' })
+      // @ts-expect-error - symbol is not Json
+      .step({ slug: 'invalid3' }, () => Symbol('x'))
+      // @ts-expect-error - function is not Json
+      .step({ slug: 'invalid4' }, () => () => 'nope');
+  });
+});