PersistentAI API Documentation / @persistentai/fireflow-vfs / server / FlowWorkflows

Class: FlowWorkflows

Defined in: packages/fireflow-vfs/src/workflows/flow-workflows.ts:129

Flow workflows class for managing flow packages in VFS

Handles:

• createFlowPackage: Create new .fflow/ folder with manifest, flow.json, events/.keep
• saveFlow: Save flow data, derive .ffevent files, cleanup orphans
• deleteFlow: Remove entire .fflow/ folder recursively
• getFlowByRef: Read flow using FlowRef addressing
• getFlowById: Lookup path from flow index, delegate to getFlowByRef
• listFlowEvents: List .ffevent files in a flow package

Extends

• ConfiguredInstance

Constructors

Constructor

new FlowWorkflows(db, name?): FlowWorkflows

Defined in: packages/fireflow-vfs/src/workflows/flow-workflows.ts:130

Parameters

db

DB

name?

string = 'FlowWorkflows'

Returns

FlowWorkflows

Overrides

ConfiguredInstance.constructor

Properties

name

readonly name: string

Defined in: node_modules/.pnpm/@dbos-inc+dbos-sdk@4.7.9_bufferutil@4.0.9_pg-native@3.5.2_utf-8-validate@5.0.10/node_modules/@dbos-inc/dbos-sdk/dist/src/decorators.d.ts:126

Inherited from

ConfiguredInstance.name

Methods

createFlowPackage()

createFlowPackage(workspaceId, branchName, path, name, description, userId): Promise<CreateFlowPackageResult>

Defined in: packages/fireflow-vfs/src/workflows/flow-workflows.ts:156

Create a new flow package (.fflow/ folder)

Creates the folder structure:

• {path}/manifest.json - Package metadata
• {path}/flow.json - Empty flow data
• {path}/events/.keep - Placeholder for events directory

Also updates the flow index (.fireflow/flow-index.json) to map flowId -> path.

Parameters

workspaceId

string

Workspace ID

branchName

string

Branch name (typically 'main')

path

string

Path for the .fflow folder (e.g., 'workflows/my-flow.fflow')

name

string

Human-readable flow name

description

Optional flow description

string | undefined

userId

string

User ID creating the flow

Returns

Promise<CreateFlowPackageResult>

Created flow package details

---

deleteFlow()

deleteFlow(workspaceId, branchName, path, userId): Promise<void>

Defined in: packages/fireflow-vfs/src/workflows/flow-workflows.ts:468

Delete a flow package (.fflow/ folder) and all its contents

Deletes:

• manifest.json
• flow.json
• events/*.ffevent files
• events/.keep
• Any other files in the .fflow/ folder

Also updates the flow index to remove the flowId -> path mapping.

Steps:

1. Check permissions
2. Read manifest to get flowId (for index cleanup and event metadata)
3. Delete all objects under the .fflow/ folder
4. Update flow index to remove flowId mapping
5. Commit
6. Emit event

Parameters

workspaceId

string

Workspace ID

branchName

string

Branch name (typically 'main')

path

string

Path to the .fflow folder

userId

string

User ID deleting the flow

Returns

Promise<void>

---

deriveEventsWorkflow()

deriveEventsWorkflow(workspaceId, flowPath, branchName, userId): Promise<DeriveEventsResult>

Defined in: packages/fireflow-vfs/src/workflows/flow-workflows.ts:844

Derive .ffevent files from a flow that's already stored in VFS.

This workflow is designed for dual-write scenarios where:

1. Flow is saved to PostgreSQL (old storage)
2. Flow is written to VFS (flow.json) by the tRPC procedure
3. This workflow derives events from the VFS file

NO large flow data in inputs - only file references! The workflow reads flow.json from VFS to derive events.

Parameters

workspaceId

string

Workspace ID

flowPath

string

Path to .fflow folder (e.g., 'workflows/my-flow.fflow')

branchName

string

Branch name (e.g., 'main')

userId

string

User performing the operation

Returns

Promise<DeriveEventsResult>

Derived and deleted event file paths

---

getFlowById()

getFlowById(workspaceId, ref, flowId, userId): Promise<GetFlowByRefResult>

Defined in: packages/fireflow-vfs/src/workflows/flow-workflows.ts:679

Get flow by ID (legacy addressing)

Looks up the path from the flow index, then delegates to getFlowByRef. This provides backward compatibility with existing flowId-based code.

Steps:

1. Check permissions
2. Read flow index
3. Lookup path for flowId
4. Delegate to getFlowByRef

Parameters

workspaceId

string

Workspace ID

ref

string

Git branch, tag, or commit (e.g., 'main')

flowId

string

The flow ID (FLW_xxx format)

userId

string

User ID requesting the flow

Returns

Promise<GetFlowByRefResult>

Flow manifest and data

---

getFlowByRef()

getFlowByRef(workspaceId, ref, path, userId): Promise<GetFlowByRefResult>

Defined in: packages/fireflow-vfs/src/workflows/flow-workflows.ts:607

Get flow by FlowRef (path-based addressing)

Reads both manifest.json and flow.json from the .fflow folder.

Steps:

1. Check permissions
2. Read manifest.json
3. Read flow.json

Parameters

workspaceId

string

Workspace ID

ref

string

Git branch, tag, or commit (e.g., 'main')

path

string

Path to the .fflow folder

userId

string

User ID requesting the flow

Returns

Promise<GetFlowByRefResult>

Flow manifest and data

---

initialize()

initialize(): Promise<void>

Defined in: node_modules/.pnpm/@dbos-inc+dbos-sdk@4.7.9_bufferutil@4.0.9_pg-native@3.5.2_utf-8-validate@5.0.10/node_modules/@dbos-inc/dbos-sdk/dist/src/decorators.d.ts:131

Override this method to perform async initialization between construction and DBOS.launch().

Returns

Promise<void>

Inherited from

ConfiguredInstance.initialize

---

listFlowEvents()

listFlowEvents(workspaceId, ref, path, userId): Promise<FlowEventInfo[]>

Defined in: packages/fireflow-vfs/src/workflows/flow-workflows.ts:764

List .ffevent files in a flow package

Returns information about all derived event files in the events/ subdirectory.

Steps:

1. Check permissions
2. List files in {path}/events/
3. Filter and return .ffevent files

Parameters

workspaceId

string

Workspace ID

ref

string

Git branch, tag, or commit (e.g., 'main')

path

string

Path to the .fflow folder

userId

string

User ID requesting the list

Returns

Promise<FlowEventInfo[]>

List of event file information

---

saveFlow()

saveFlow(workspaceId, branchName, path, flowData, userId): Promise<SaveFlowResult>

Defined in: packages/fireflow-vfs/src/workflows/flow-workflows.ts:326

Save flow data and derive .ffevent files

Steps:

1. Check permissions
2. Read current manifest
3. Write flow.json
4. Derive .ffevent files and clean up orphans (via deriveEventsFromFile)
5. Update manifest.json updatedAt
6. Commit
7. Emit event

Parameters

workspaceId

string

Workspace ID

branchName

string

Branch name (typically 'main')

path

string

Path to the .fflow folder

flowData

Record<string, unknown>

Serialized flow data to save

userId

string

User ID saving the flow

Returns

Promise<SaveFlowResult>

Save result with derived events info