Serialization - CrystalFlow

CrystalFlow workflows are fully serializable to JSON, enabling persistent storage, version control, and sharing.

Why Serialization?

Persistence

Save workflows to files or databases

Version Control

Track changes with Git

Sharing

Share workflows across teams

Templates

Create reusable workflow templates

Serialization API

To JSON

Convert a workflow to JSON:

import { serializeWorkflow } from '@crystalflow/core';

// Get workflow data
const workflowData = workflow.toJSON();

// Serialize to JSON string
const json = serializeWorkflow(workflowData);

// Save to file
import fs from 'fs';
fs.writeFileSync('my-workflow.json', json);

From JSON

Load a workflow from JSON:

import { deserializeWorkflow, Workflow } from '@crystalflow/core';
import fs from 'fs';

// Read JSON file
const json = fs.readFileSync('my-workflow.json', 'utf-8');

// Deserialize
const workflowData = deserializeWorkflow(json);

// Create workflow instance
const workflow = Workflow.fromJSON(workflowData);

JSON Format

Workflows serialize to this format:

{
  "version": "1.0.0",
  "id": "workflow-123",
  "name": "My Workflow",
  "description": "Optional description",
  "nodes": [
    {
      "id": "node-1",
      "type": "math.add",
      "position": { "x": 100, "y": 100 },
      "inputs": { "a": 10, "b": 20 },
      "properties": {}
    }
  ],
  "connections": [
    {
      "id": "conn-1",
      "source": "node-1",
      "sourceOutput": "result",
      "target": "node-2",
      "targetInput": "value"
    }
  ],
  "variables": {
    "apiKey": "your-key"
  }
}

Save to File

Node.js

import fs from 'fs';
import { serializeWorkflow } from '@crystalflow/core';

function saveWorkflow(workflow, filename) {
  const json = serializeWorkflow(workflow.toJSON());
  fs.writeFileSync(filename, json);
  console.log(`Workflow saved to ${filename}`);
}

saveWorkflow(workflow, 'workflows/my-workflow.json');

Browser

import { serializeWorkflow } from '@crystalflow/core';

function downloadWorkflow(workflow, filename) {
  const json = serializeWorkflow(workflow.toJSON());
  const blob = new Blob([json], { type: 'application/json' });
  const url = URL.createObjectURL(blob);
  
  const a = document.createElement('a');
  a.href = url;
  a.download = filename;
  a.click();
  
  URL.revokeObjectURL(url);
}

downloadWorkflow(workflow, 'my-workflow.json');

Load from File

Node.js

import fs from 'fs';
import { deserializeWorkflow, Workflow } from '@crystalflow/core';

function loadWorkflow(filename) {
  const json = fs.readFileSync(filename, 'utf-8');
  const workflowData = deserializeWorkflow(json);
  return Workflow.fromJSON(workflowData);
}

const workflow = loadWorkflow('workflows/my-workflow.json');

Browser

import { deserializeWorkflow, Workflow } from '@crystalflow/core';

function uploadWorkflow(file) {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    
    reader.onload = (e) => {
      try {
        const json = e.target.result;
        const workflowData = deserializeWorkflow(json);
        const workflow = Workflow.fromJSON(workflowData);
        resolve(workflow);
      } catch (error) {
        reject(error);
      }
    };
    
    reader.onerror = reject;
    reader.readAsText(file);
  });
}

// Usage with file input
const fileInput = document.getElementById('file-input');
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  const workflow = await uploadWorkflow(file);
  console.log('Workflow loaded:', workflow);
});

React Integration

Save Button

import { serializeWorkflow } from '@crystalflow/core';

function SaveButton({ workflow }) {
  const handleSave = () => {
    const json = serializeWorkflow(workflow.toJSON());
    const blob = new Blob([json], { type: 'application/json' });
    const url = URL.createObjectURL(blob);
    
    const a = document.createElement('a');
    a.href = url;
    a.download = `workflow-${workflow.id}.json`;
    a.click();
    
    URL.revokeObjectURL(url);
  };
  
  return <button onClick={handleSave}>Save Workflow</button>;
}

Load Button

import { deserializeWorkflow, Workflow } from '@crystalflow/core';
import { useRef } from 'react';

function LoadButton({ onWorkflowLoad }) {
  const fileInputRef = useRef(null);
  
  const handleLoad = () => {
    fileInputRef.current?.click();
  };
  
  const handleFileChange = async (e) => {
    const file = e.target.files[0];
    if (!file) return;
    
    const reader = new FileReader();
    reader.onload = (e) => {
      const json = e.target.result;
      const workflowData = deserializeWorkflow(json);
      const workflow = Workflow.fromJSON(workflowData);
      onWorkflowLoad(workflow);
    };
    reader.readAsText(file);
  };
  
  return (
    <>
      <button onClick={handleLoad}>Load Workflow</button>
      <input
        ref={fileInputRef}
        type="file"
        accept=".json"
        style={{ display: 'none' }}
        onChange={handleFileChange}
      />
    </>
  );
}

LocalStorage

Save to LocalStorage

function saveToLocalStorage(workflow) {
  const json = serializeWorkflow(workflow.toJSON());
  localStorage.setItem('workflow', json);
}

Load from LocalStorage

function loadFromLocalStorage() {
  const json = localStorage.getItem('workflow');
  if (!json) return null;
  
  const workflowData = deserializeWorkflow(json);
  return Workflow.fromJSON(workflowData);
}

Auto-Save Hook

import { useEffect } from 'react';
import { serializeWorkflow } from '@crystalflow/core';

function useAutoSave(workflow, interval = 30000) {
  useEffect(() => {
    const timer = setInterval(() => {
      if (workflow) {
        const json = serializeWorkflow(workflow.toJSON());
        localStorage.setItem('workflow-autosave', json);
        console.log('Workflow auto-saved');
      }
    }, interval);
    
    return () => clearInterval(timer);
  }, [workflow, interval]);
}

Validation

Validate JSON before deserializing:

import { validateWorkflowJSON } from '@crystalflow/core';

const json = fs.readFileSync('workflow.json', 'utf-8');
const errors = validateWorkflowJSON(json);

if (errors.length > 0) {
  console.error('Validation errors:', errors);
  errors.forEach(error => {
    console.error(`- ${error.message}`);
  });
} else {
  const workflowData = deserializeWorkflow(json);
  const workflow = Workflow.fromJSON(workflowData);
}

Version Control with Git

Initialize Repository

mkdir workflows
cd workflows
git init

Commit Workflows

git add my-workflow.json
git commit -m "Add data processing workflow"

View Changes

git diff my-workflow.json

Track History

git log --oneline my-workflow.json

Restore Previous Version

git checkout HEAD~1 my-workflow.json

Export Formats

Pretty Print

const json = serializeWorkflow(workflowData, {
  pretty: true,
  indent: 2
});

Minified

const json = serializeWorkflow(workflowData, {
  pretty: false
});

Database Storage

SQL Database

import { serializeWorkflow, deserializeWorkflow, Workflow } from '@crystalflow/core';
import { db } from './database';

async function saveWorkflowToDatabase(workflow) {
  const json = serializeWorkflow(workflow.toJSON());
  
  await db.query(
    'INSERT INTO workflows (id, name, data) VALUES (?, ?, ?)',
    [workflow.id, workflow.name, json]
  );
}

async function loadWorkflowFromDatabase(id) {
  const result = await db.query(
    'SELECT data FROM workflows WHERE id = ?',
    [id]
  );
  
  const workflowData = deserializeWorkflow(result.data);
  return Workflow.fromJSON(workflowData);
}

MongoDB

import { serializeWorkflow, deserializeWorkflow, Workflow } from '@crystalflow/core';
import { MongoClient } from 'mongodb';

async function saveWorkflow(workflow) {
  const client = await MongoClient.connect(process.env.MONGODB_URI);
  const db = client.db('workflows');
  
  await db.collection('workflows').insertOne({
    id: workflow.id,
    name: workflow.name,
    data: workflow.toJSON(),
    createdAt: new Date()
  });
  
  await client.close();
}

async function loadWorkflow(id) {
  const client = await MongoClient.connect(process.env.MONGODB_URI);
  const db = client.db('workflows');
  
  const doc = await db.collection('workflows').findOne({ id });
  await client.close();
  
  return Workflow.fromJSON(doc.data);
}

Best Practices

Validate Before Saving

Always validate workflows before serialization to catch errors early.

Use Version Control

Store workflows in Git for history tracking and collaboration.

Add Metadata

Include name, description, and version in workflow JSON.

Handle Secrets Carefully

Never serialize sensitive data - use variables at runtime.

Auto-Save Regularly

Implement auto-save to prevent data loss.

Next Steps

JSON Schema

Understanding the JSON format

Workflow API

Complete Workflow API

Version Control Guide

Git best practices (coming soon)

Migration

Version migration (coming soon)

​Why Serialization?

Persistence

Version Control

Sharing

Templates

​Serialization API

​To JSON

​From JSON

​JSON Format

​Save to File

​Node.js

​Browser

​Load from File

​Node.js

​Browser

​React Integration

​Save Button

​Load Button

​LocalStorage

​Save to LocalStorage

​Load from LocalStorage

​Auto-Save Hook

​Validation

​Version Control with Git

​Initialize Repository

​Commit Workflows

​View Changes

​Track History

​Restore Previous Version

​Export Formats

​Pretty Print

​Minified

​Database Storage

​SQL Database

​MongoDB

​Best Practices

​Next Steps

JSON Schema

Workflow API

Version Control Guide

Migration

Why Serialization?

Serialization API

To JSON

From JSON

JSON Format

Save to File

Node.js

Browser

Load from File

Node.js

Browser

React Integration

Save Button

Load Button

LocalStorage

Save to LocalStorage

Load from LocalStorage

Auto-Save Hook

Validation

Version Control with Git

Initialize Repository

Commit Workflows

View Changes

Track History

Restore Previous Version

Export Formats

Pretty Print

Minified

Database Storage

SQL Database

MongoDB

Best Practices

Next Steps