⚠️ Experimental Package: This package is currently under development and should not be used in production. The API may change.

A lightweight SQLite-based workflow tracker for Node.js applications.

• Simple workflow management
• Step tracking
• Identifier-based workflow lookup
• Workflow statistics
• SQLite-based storage
• TypeScript support
• Bulk operations support
• Performance optimizations
• Centralized error handling
• Graceful error recovery

npm install liteflow

import { Liteflow } from 'liteflow'; // Initialize with a database path const liteflow = new Liteflow('path/to/database.db'); liteflow.init(); // Start a new workflow - returns a WorkflowInstance const workflow = liteflow.startWorkflow('test-workflow', [ { key: 'test', value: '123' } ]); // NEW: Use the workflow instance methods directly workflow.addStep('step1', { data: 'test1' }); workflow.addStep('step2', { data: 'test2' }); workflow.complete(); // Or use the traditional API (still supported) const workflowId = workflow.id; // Get the workflow ID liteflow.addStep(workflowId, 'step1', { data: 'test1' }); liteflow.addStep(workflowId, 'step2', { data: 'test2' }); liteflow.completeWorkflow(workflowId); // Get workflow by identifier const foundWorkflow = liteflow.getWorkflowByIdentifier('test', '123'); // Get workflow steps const steps = workflow.getSteps(); // Using instance method // or const stepsById = liteflow.getSteps(workflowId); // Using traditional method // Get steps by identifier const stepsByIdentifier = liteflow.getStepsByIdentifier('test', '123'); // Get workflow statistics const stats = liteflow.getWorkflowStats(); // Get workflows with pagination and filtering const workflows = liteflow.getWorkflows({ status: 'completed', page: 1, pageSize: 10, orderBy: 'started_at', order: 'desc' }); // Delete a workflow const deleted = workflow.delete(); // Using instance method // or const deletedById = liteflow.deleteWorkflow(workflowId); // Using traditional method if (deleted) { console.log('Workflow deleted successfully'); } // Delete all workflows const allDeleted = liteflow.deleteAllWorkflows(); if (allDeleted) { console.log('All workflows deleted successfully'); } // Attach additional identifiers liteflow.attachIdentifier('test', '123', { key: 'test2', value: '456' }); // Get most frequent steps const frequentSteps = liteflow.getMostFrequentSteps(5); // Get average step duration const stepDurations = liteflow.getAverageStepDuration();

Creates a new Liteflow instance.

Initializes the database schema.

Liteflow implements a centralized error handling mechanism through the wrap function. This ensures that:

• All database operations are wrapped in try-catch blocks
• Errors are logged to the console
• Operations return fallback values instead of throwing errors
• System stability is maintained even when errors occur

Fallback values for different operations:

• getWorkflows: { workflows: [], total: 0, page: 1, pageSize: 10, totalPages: 0 }
• getSteps and getStepsByIdentifier: []
• getWorkflowStats: { total: 0, completed: 0, pending: 0, avgSteps: 0 }
• getMostFrequentSteps and getAverageStepDuration: []
• attachIdentifier, deleteWorkflow, deleteAllWorkflows: false

Starts a new workflow and returns a WorkflowInstance object that provides convenient instance methods.

The WorkflowInstance returned by startWorkflow provides the following methods:

• workflow.id: Get the workflow ID (string)
• workflow.addStep(step: string, data: any): Add a step to this workflow
• workflow.complete(): Mark this workflow as completed
• workflow.fail(reason?: string): Mark this workflow as failed
• workflow.getSteps(): Get all steps for this workflow
• workflow.delete(): Delete this workflow

Adds a step to a workflow. Accepts either a workflow ID string or a WorkflowInstance.

Marks a workflow as completed. Accepts either a workflow ID string or a WorkflowInstance.

Retrieves a workflow by its identifier.

Gets all steps for a workflow.

Gets all steps for workflows matching the given identifier key and value.

Returns workflow statistics.

Attaches a new identifier to an existing workflow. Returns true if successful, false if the workflow doesn't exist or if the identifier already exists.

Returns the most frequent steps across all workflows, limited by the specified number.

Returns average step duration for workflows.

Retrieves workflows with pagination, filtering and sorting options.

Options:

• status?: 'pending' | 'completed' | 'failed' - Filter by workflow status
• page?: number - Page number (default: 1)
• pageSize?: number - Items per page (default: 10)
• orderBy?: 'started_at' | 'ended_at' - Field to sort by (default: 'started_at')
• order?: 'asc' | 'desc' - Sort order (default: 'desc')
• identifier?: { key: string, value: string } - Filter by identifier key and value

Deletes a workflow and all its steps. Returns true if the workflow was deleted successfully, false if the workflow doesn't exist or if there was an error.

Deletes all workflows and their steps. Returns true if the operation was successful, false if there was an error.

interface Identifier { key: string; value: string; } interface Workflow { id: string; name: string; identifiers: string; status: 'pending' | 'completed' | 'failed'; started_at: string; ended_at?: string; } interface WorkflowStep { id: string; workflow_id: string; step: string; data: string; created_at: string; } interface WorkflowStats { total: number; completed: number; pending: number; avgSteps: number; } interface GetWorkflowsOptions { status?: 'pending' | 'completed' | 'failed'; page?: number; pageSize?: number; orderBy?: 'started_at' | 'ended_at'; order?: 'asc' | 'desc'; identifier?: { key: string; value: string; }; }

git clone https://github.com/indatawetrust/liteflow.git cd liteflow npm install

npm test

npm run benchmark

MIT