🪄 chain-enhance

Sequentially chain multiple SvelteKit 5 form actions with deep-merged data propagation, type-safe results, reactive progress tracking, and automatic file-safety.

Designed for real multi-stage workflows like upload → parse → SEO → save → publish.

🌐 See It In Action

Live Demo:
🔗 https://chain-enhance.michaelcuneo.com.au

This demo showcases a full multi-step content workflow using
@michaelcuneo/chain-enhance — including file upload, markdown parsing,
SEO generation, database save simulation, and publish confirmation —
all chained seamlessly with real-time progress tracking.

Built with SvelteKit 5, TypeScript, and SST v3.
Deployed on AWS via CloudFront + Lambda.

🚀 Install

npm i chain-enhance
# or
pnpm add chain-enhance

⚙️ Basic Usage

1️⃣ Attach the enhancer to a form

<script lang="ts">
	import { chainEnhance, formChain } from 'chain-enhance';
	import { goto } from '$app/navigation';

	let formState = $state<'idle' | 'running' | 'complete' | 'error'>('idle');
	let result: Record<string, any> = $state({});

	const chained = chainEnhance(['markdown', 'seo', 'save', 'publish'], {
		onStep: (step, data, index, total) => {
			console.log(`Step ${index}/${total}: ${step}`, data);
			formState = 'running';
		},
		onSuccess: (final) => {
			console.log('✅ Chain complete', final);
			result = final.final ?? {};
			formState = 'complete';
			goto('/success');
		},
		onError: (err) => {
			console.error('❌ Chain failed', err);
			formState = 'error';
		}
	});
</script>

<form method="POST" action="?/upload" use:chained enctype="multipart/form-data">
	<input type="text" name="title" required />
	<input type="file" name="featuredImage" accept="image/*" required />
	<button>Start Workflow</button>
</form>

{#if formState === 'running'}
	<p>⚙️ Running workflow — step {$formChain.current} of {$formChain.total}</p>
{/if}

2️⃣ Define Server Actions

Each step must return the standardized ChainStepResponse shape.

import type { ChainStepResponse } from 'chain-enhance';

export const actions = {
	upload: async ({ request }): Promise<ChainStepResponse> => {
		const data = await request.formData();
		const title = data.get('title')?.toString();
		const file = data.get('featuredImage') as File;

		await new Promise((r) => setTimeout(r, 800)); // simulate upload

		return {
			step: 'upload',
			ok: true,
			message: 'File uploaded',
			data: {
				title,
				featuredImageName: file.name
			}
		};
	},

	markdown: async ({ request }): Promise<ChainStepResponse> => {
		const prev = JSON.parse((await request.formData()).get('__previous')?.toString() ?? '{}');
		await new Promise((r) => setTimeout(r, 800));

		return {
			step: 'markdown',
			ok: true,
			message: 'Markdown processed',
			data: {
				wordCount: prev.description?.split(/\s+/).length ?? 0
			}
		};
	},

	seo: async ({ request }): Promise<ChainStepResponse> => {
		const prev = JSON.parse((await request.formData()).get('__previous')?.toString() ?? '{}');
		await new Promise((r) => setTimeout(r, 800));

		return {
			step: 'seo',
			ok: true,
			message: 'SEO metadata generated',
			data: {
				meta: {
					title: prev.title,
					description: prev.abstract,
					keywords: ['svelte', 'chain', 'form']
				}
			}
		};
	},

	save: async ({ request }): Promise<ChainStepResponse> => {
		const prev = JSON.parse((await request.formData()).get('__previous')?.toString() ?? '{}');
		await new Promise((r) => setTimeout(r, 800));

		return {
			step: 'save',
			ok: true,
			message: 'Saved to database',
			data: {
				projectId: crypto.randomUUID(),
				timestamp: new Date().toISOString()
			}
		};
	},

	publish: async ({ request }): Promise<ChainStepResponse> => {
		const prev = JSON.parse((await request.formData()).get('__previous')?.toString() ?? '{}');
		await new Promise((r) => setTimeout(r, 800));

		return {
			step: 'publish',
			ok: true,
			message: `Project "${prev.title}" published successfully!`,
			data: {}
		};
	}
};

🧱 Type Contracts

export interface ChainStepData {
	[key: string]: unknown;
}

/** Response shape required from each action step. */
export interface ChainStepResponse {
	step: string; // step name
	ok: boolean; // success flag
	message?: string; // optional short message
	data?: ChainStepData; // optional structured payload
}

/** Accumulated result returned to `onSuccess`. */
export interface ChainCombinedResult extends ChainStepResponse {
	history?: ChainStepResponse[]; // all intermediate step responses
	final?: ChainStepData; // deeply merged result
}

/** Lifecycle callbacks for `chainEnhance`. */
export interface ChainEnhanceCallbacks {
	onStep?: (step: string, data: ChainStepData, index: number, total: number) => void;
	onSuccess?: (result: ChainCombinedResult) => void;
	onError?: (error: unknown) => void;
}

🔗 How It Works

1. The first form submission runs normally via enhance().

2. Its result’s data becomes the base payload.

3. Each next action is called with:

   fd.append('__previous', JSON.stringify(combined));

4. Step responses are validated and deeply merged:

   combined = deepMerge(combined, response.data);

5. After all steps complete, onSuccess fires with the merged ChainCombinedResult.

Important rules

• Files/Blobs: only supported in the first step. Later steps receive JSON only.
• Any error, ok: false, or thrown exception stops the chain.
• Each step’s duration and result are recorded in history.

🧠 Deep Merge & Automatic Data Forwarding

Each step in your workflow receives the full, merged dataset from all previous steps —
you no longer need to manually forward every field like title, description, or meta.

chainEnhance performs a recursive deep merge between step results:

• Objects are merged deeply so nested keys are preserved.
• Arrays merge by index — new elements replace or extend existing ones.
• Primitives overwrite only when defined (avoiding accidental wipes).

// Step 1 (upload)
data: {
  title: 'My Project',
  description: 'Full markdown description...',
  meta: { keywords: ['svelte', 'chain'] }
}

// Step 2 (seo)
data: {
  meta: { description: 'SEO summary' }
}

// ✅ Combined result after step 2
{
  title: 'My Project',
  description: 'Full markdown description...',
  meta: {
    keywords: ['svelte', 'chain'],
    description: 'SEO summary'
  }
}

---

## 📊 Reactive Progress Store

The `formChain` store tracks real-time progress across the workflow.

```ts
import { formChain } from 'chain-enhance';

$formChain = {
	step: 'seo',
	current: 3,
	total: 5,
	percent: 60,
	ok: true,
	message: 'SEO metadata generated',
	data: { meta: {...} }
};

API

export interface ChainProgress {
	step: 'idle' | 'initial' | 'complete' | 'error' | string;
	current: number;
	total: number;
	percent: number;
	ok?: boolean;
	message?: string;
	data?: Record<string, unknown>;
	error?: unknown;
}

startStep(step, data?, current?, total?)
completeStep(final)
failStep(error)

🧾 Example Final Result

{
	"step": "publish",
	"ok": true,
	"message": "Completed 5 chained actions in 5021.44ms.",
	"final": {
		"title": "Demo Project",
		"featuredImageName": "cat.jpg",
		"wordCount": 243,
		"meta": {
			"title": "Demo Project",
			"description": "SEO generated description",
			"keywords": ["svelte", "chain", "form"]
		},
		"projectId": "0fa69e9c-74e8-465d-b8b0-62fa8b6d958d",
		"timestamp": "2025-10-30T14:32:10.202Z"
	},
	"history": [
		{ "step": "upload", "ok": true, "message": "File uploaded" },
		{ "step": "markdown", "ok": true, "message": "Markdown processed" },
		{ "step": "seo", "ok": true, "message": "SEO metadata generated" },
		{ "step": "save", "ok": true, "message": "Saved to database" },
		{ "step": "publish", "ok": true, "message": "Project \"Demo Project\" published successfully!" }
	]
}

⚙️ API Reference

chainEnhance(actions: string[], options?: ChainEnhanceCallbacks): (form: HTMLFormElement) => void

| Parameter | Type | Description | | ------------------- | -------------------------------- | ------------------------------------------------- | | actions | string[] | Ordered list of action names to chain | | options.onStep | (step, data, i, total) => void | Fired after each successful step | | options.onSuccess | (result) => void | Fired when all steps complete | | options.onError | (err) => void | Fired on network, parsing, or ok:false failures |

✅ Compatibility

| Feature | Status | | --------------------------- | ------ | | SvelteKit 2 / 5 (runes) | ✅ | | TypeScript | ✅ | | Multipart (first step only) | ✅ | | Deep merge data propagation | ✅ | | Reactive progress store | ✅ | | SSR + SPA | ✅ |

🧱 License

MIT © Michael Cuneo (2025)

TL;DR

chainEnhance() = enhance() on steroids

Upload → Parse → SEO → Save → Publish → Done

• Each step returns { step, ok, message?, data? }
• data objects deep-merge between steps
• Files supported only in step 1
• Reactive formChain store tracks progress
• Fully typed · Zero boilerplate 🪄