Preparing for v1.0.0 Migration

This guide helps you prepare your ZoopFlow v0.x implementation for a smooth migration to v1.0.0 when it's released.

Key Changes to Prepare For

1. Step Definition API

In v1.0.0, steps will use the defineStep function and require explicit schemas:

import { defineStep } from '@zoopflow/core';
 
const myStep = defineStep({
  id: 'my-step',
  version: '1.0.0',
  input_schema: { /* JSON Schema */ },
  output_schema: { /* JSON Schema */ },
  execute: async (input, context) => {
    // Step logic
  }
});

Preparation Actions:

• Start adding explicit JSON schemas to your steps
• Follow the [namespace].[name] format for step IDs
• Ensure your steps are properly typed

2. Flow Definition API

In v1.0.0, flows will use the defineFlow function and require explicit schemas:

import { defineFlow } from '@zoopflow/core';
 
const myFlow = defineFlow({
  id: 'my-flow',
  version: '1.0.0',
  input_schema: { /* JSON Schema */ },
  output_schema: { /* JSON Schema */ },
  steps: async (input, context) => {
    // Flow logic
  }
});

Preparation Actions:

• Start adding explicit JSON schemas to your flows
• Follow the [namespace].[name] format for flow IDs
• Ensure your flows are properly typed

3. Enhanced Context API

The context API is being enhanced in v1.0.0:

// New logger API
context.logger.info('Message');
context.logger.error('Error message', { details: error });
 
// Checkpoints for state persistence
await context.createCheckpoint(state);
 
// Service discovery
const service = context.getService('serviceName');

Preparation Actions:

• Update your context usage to use the new logger API
• Consider adding checkpoints for better state management
• Use the service discovery for better dependency management

4. Structured Error Handling

v1.0.0 will include a more structured approach to error handling:

import { defineFlow, FlowError } from '@zoopflow/core';
 
const myFlow = defineFlow({
  // ...
  errorHandler: async (error, context) => {
    if (error instanceof PaymentError) {
      // Handle payment errors
      return { success: false, error: 'Payment failed' };
    }
    // Re-throw other errors
    throw error;
  }
});

Preparation Actions:

• Start adding explicit error handlers to your flows
• Consider using the error classification system
• Use custom error classes for domain-specific errors

Migration Readiness Checklist

• Add explicit JSON schemas to all steps and flows
• Follow the recommended ID format for all components
• Update context usage to prepare for the new API
• Implement structured error handling
• Add proper TypeScript types to all components
• Test your workflows with the pre-release validation tools