Note: This document describes Pocket's 14 built-in node types. These are native to the framework and are NOT plugins. They provide core functionality out of the box without requiring any additional installation.
For extending Pocket with custom functionality beyond these built-in types, see the Plugin System documentation.
This document provides comprehensive documentation for all built-in nodes in Pocket. Each node includes configuration options, examples, and best practices.
Output a message and pass through input data unchanged.
Category: core
Since: v0.1.0
type: echo
config:
message: string # Message to output (supports templating)- name: log-step
type: echo
config:
message: "Processing order {{.order_id}} with total: {{.total}}"Add a delay to workflow execution.
Category: core
Since: v0.1.0
type: delay
config:
duration: string # Duration (e.g., "1s", "500ms", "2m")- name: rate-limit
type: delay
config:
duration: "1s" # Wait 1 second between API callsStatic routing to different nodes based on configuration.
Category: core
Since: v0.1.0
type: router
config:
routes:
route_name: target_node # Map of route names to node targets
default: string # Default target if no route matches- name: route-by-type
type: router
config:
routes:
create: handle-create
update: handle-update
delete: handle-delete
default: handle-unknownDynamic routing based on template expressions.
Category: core
Since: v0.2.0
type: conditional
config:
conditions:
- if: string # Go template expression
then: string # Target node if condition is true
else: string # Default target if no conditions match- name: route-by-score
type: conditional
config:
conditions:
- if: "{{gt .score 0.9}}"
then: high-priority
- if: "{{gt .score 0.5}}"
then: medium-priority
else: low-priorityTransform data using JQ expressions.
Category: data
Since: v0.1.0
type: transform
config:
jq: string # JQ expression for transformation- name: extract-items
type: transform
config:
jq: |
.data.items | map({
id,
name: .title,
price: .cost * 1.2,
category: .tags[0]
})Render Go templates with input data.
Category: data
Since: v0.1.0
type: template
config:
template: string # Go template string
template_file: string # Or path to template file
output: string # Output format: "string" (default) or "json"- name: format-message
type: template
config:
template: |
Order Summary:
Customer: {{.customer.name}}
Items: {{len .items}}
Total: ${{.total}}
{{range .items}}
- {{.name}}: ${{.price}}
{{end}}Extract data using JSONPath expressions.
Category: data
Since: v0.2.0
type: jsonpath
config:
path: string # JSONPath expression
default: any # Default value if path not found
unwrap: boolean # Unwrap single-element arrays (default: false)- name: get-user-email
type: jsonpath
config:
path: "$.users[?(@.active==true)].email"
unwrap: true
default: "no-email@example.com"Validate data against JSON Schema.
Category: data
Since: v0.2.0
type: validate
config:
schema: object # JSON Schema definition
schema_file: string # Or path to schema file
on_error: string # "fail" (default) or "pass"- name: validate-order
type: validate
config:
schema:
type: object
properties:
order_id:
type: string
pattern: "^ORD-[0-9]+$"
items:
type: array
minItems: 1
items:
type: object
required: [sku, quantity]
required: [order_id, items]Collect and combine data from multiple sources.
Category: data
Since: v0.2.0
type: aggregate
config:
mode: string # "array", "object", "merge", or "concat"
key: string # Template for object keys (mode: object)
timeout: string # Max wait time (e.g., "30s")
min_items: int # Minimum items before proceeding- name: collect-results
type: aggregate
config:
mode: object
key: "{{.source}}"
timeout: "5s"
min_items: 3Make HTTP requests with retry and timeout support.
Category: io
Since: v0.1.0
type: http
config:
url: string # URL (supports templating)
method: string # GET, POST, PUT, DELETE, PATCH
headers: object # HTTP headers
body: any # Request body (for POST/PUT/PATCH)
timeout: string # Request timeout (default: "30s")
retry:
max_attempts: int # Maximum retry attempts (default: 3)
delay: string # Delay between retries (default: "1s")- name: call-api
type: http
config:
url: "https://api.example.com/users/{{.user_id}}"
method: POST
headers:
Content-Type: application/json
Authorization: "Bearer {{.token}}"
body:
action: update
data: "{{.updates}}"
retry:
max_attempts: 5
delay: "2s"Read from or write to files with path sandboxing.
Category: io
Since: v0.2.0
type: file
config:
path: string # File path (supports templating)
mode: string # "read", "write", "append", or "list"
content: string # Content for write/append (supports templating)
create_dirs: boolean # Create parent directories (default: false)
sandbox: string # Restrict to directory (default: current dir)- name: save-results
type: file
config:
path: "output/results-{{.timestamp}}.json"
mode: write
content: "{{.results | json}}"
create_dirs: trueExecute shell commands with restrictions.
Category: io
Since: v0.2.0
type: exec
config:
command: string # Command to execute
args: array # Command arguments
env: object # Environment variables
timeout: string # Execution timeout (default: "30s")
allowed_commands: array # Whitelist of allowed commands
capture_output: boolean # Capture stdout/stderr (default: true)- name: process-file
type: exec
config:
command: jq
args:
- ".items | length"
- "data.json"
timeout: "10s"
allowed_commands: ["jq", "grep", "sed"]Execute multiple tasks concurrently.
Category: flow
Since: v0.3.0
type: parallel
config:
tasks: array # List of tasks to execute
max_concurrency: int # Max concurrent tasks (default: unlimited)
fail_fast: boolean # Stop on first error (default: true)
timeout: string # Overall timeouttasks:
- name: string # Task name
node: string # Node type to execute
config: object # Node configuration
input: any # Input data for the task- name: fetch-all-data
type: parallel
config:
max_concurrency: 3
fail_fast: false
timeout: "30s"
tasks:
- name: fetch-users
node: http
config:
url: "https://api.example.com/users"
- name: fetch-orders
node: http
config:
url: "https://api.example.com/orders"
- name: fetch-products
node: http
config:
url: "https://api.example.com/products"Execute Lua scripts for custom logic.
Category: script
Since: v0.4.0
type: lua
config:
script: string # Inline Lua script
file: string # Or path to script file
timeout: string # Script timeout (default: "30s")
sandbox: boolean # Enable sandboxing (default: true)json_encode(value)- Encode value as JSONjson_decode(json_string)- Decode JSON stringstr_trim(string)- Trim whitespacestr_split(string, delimiter)- Split stringstr_contains(string, substring)- Check if containsstr_replace(string, old, new, [count])- Replace occurrencestype_of(value)- Get value type
- name: process-data
type: lua
config:
script: |
-- Access input data
local items = input.items or {}
-- Process items
local processed = {}
local total = 0
for i, item in ipairs(items) do
if item.active then
local p = {
id = item.id,
name = str_trim(item.name),
value = item.price * (1 - (item.discount or 0))
}
table.insert(processed, p)
total = total + p.value
end
end
-- Return result
return {
items = processed,
total = total,
count = #processed,
metadata = {
processed_at = os.time(),
original_count = #items
}
}Always handle potential errors in your node configurations:
# Good: Includes error handling
- name: api-call
type: http
config:
url: "https://api.example.com/data"
retry:
max_attempts: 3
timeout: "10s"
successors:
- action: success
target: process-data
- action: error
target: handle-errorValidate inputs before processing:
# Validate before processing
- name: validate-input
type: validate
config:
schema:
type: object
required: [id, data]
- name: process
type: transform
config:
jq: ".data | map(. + {processed: true})"Templates are powerful but can be complex:
# Good: Clear, simple template
config:
message: "Processing {{.count}} items for user {{.user_id}}"
# Avoid: Complex logic in templates
config:
message: "{{if gt .count 10}}Many{{else}}Few{{end}} items"
# Use conditional node insteadBe mindful of timeouts and resource limits:
# Set appropriate timeouts
- name: long-operation
type: exec
config:
command: "./process.sh"
timeout: "5m" # Allow enough time
# Limit concurrency
- name: batch-process
type: parallel
config:
max_concurrency: 5 # Don't overwhelm the system| Feature | Built-in Nodes | Lua Script | WASM Plugins |
|---|---|---|---|
| Performance | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |
| Flexibility | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Security | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Ease of Use | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |
| Debugging | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| Language Support | Go only | Lua only | TypeScript, Rust, Go, etc. |
- Plugin System Overview - Extend Pocket beyond built-in nodes
- WebAssembly Plugins - Creating WASM plugins
- Node Reference - Auto-generated API reference
- Examples - Real-world workflow examples