Migration Guide: v0.x to v1.0.0

This guide helps you migrate from ZoopFlow v0.x pre-release versions to the stable v1.0.0 release.

Breaking Changes

1. Step Definition API

v0.x:

const myStep = {
  id: 'my-step',
  version: '0.1.0',
  execute: async (input, context) => {
    // Step logic
  }
};

v1.0.0:

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
  }
});

2. Flow Definition API

v0.x:

const myFlow = {
  id: 'my-flow',
  version: '0.1.0',
  steps: async (input, context) => {
    // Flow logic
  }
};

v1.0.0:

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
  }
});

3. Schema Validation

Schema validation is now required for all steps and flows. The input_schema and output_schema properties are mandatory.

4. Context API

The context API has been updated to provide more functionality:

v0.x:

context.log('info', 'Message');
context.executeStep(step, input);

v1.0.0:

context.logger.info('Message');
await context.executeStep(step, input, options);
await context.createCheckpoint(state);
const service = context.getService('serviceName');

Step-by-Step Migration Guide

1. Update Dependencies

npm install @zoopflow/core@1.0.0

2. Update Step Definitions

1. Replace step object literals with defineStep calls
2. Add input and output schemas to all steps
3. Update step IDs to use the recommended format: [namespace].[name]
4. Update step versions to reflect the new API version

3. Update Flow Definitions

1. Replace flow object literals with defineFlow calls
2. Add input and output schemas to all flows
3. Update flow IDs to use the recommended format: [namespace].[name]
4. Update flow versions to reflect the new API version

4. Update Context Usage

1. Replace context.log(level, message) with context.logger[level](message)
2. Update any use of deprecated context methods

5. Update Error Handling

Error handling now follows a more structured approach:

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;
  }
});

Testing Your Migration

After migrating, test your workflows thoroughly to ensure they work as expected with the new API. Pay special attention to:

1. Schema validation for inputs and outputs
2. Error handling and recovery
3. Context method usage
4. Step and flow execution