@n8n/workflow-sdk 0.8.0 → 0.10.0

package/dist/prompts/best-practices/guides/data-persistence.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataPersistenceBestPractices = void 0;
+const types_1 = require("../types");
+class DataPersistenceBestPractices {
+    constructor() {
+        this.technique = types_1.WorkflowTechnique.DATA_PERSISTENCE;
+        this.version = '1.0.0';
+        this.documentation = `# Best Practices: Data Persistence
+
+## Overview
+
+Data persistence involves storing, updating, or retrieving records from durable storage systems. This technique is essential when you need to maintain data beyond the lifetime of a single workflow execution, or when you need to access existing data that users have stored in their spreadsheets, tables, or databases as part of your workflow logic.
+
+## When to Use Data Persistence
+
+Use data persistence when you need to:
+- Store workflow results for later retrieval or audit trails
+- Maintain records that multiple workflows can access and update
+- Create a centralized data repository for your automation
+- Archive historical data for reporting or compliance
+- Build data that persists across workflow executions
+- Track changes or maintain state over time
+- Store raw form inputs
+
+## Choosing the Right Storage Node
+
+### Data Table (n8n-nodes-base.dataTable) - PREFERRED
+
+**Best for:** Quick setup, small to medium amounts of data
+
+Advantages:
+- No credentials or external configuration required
+- Built directly into n8n
+- Fast and reliable for small to medium datasets
+- Ideal for prototyping and internal workflows
+- No additional costs or external dependencies
+
+When to use:
+- Internal workflow data storage
+- Temporary or staging data
+- Admin/audit trails
+- Simple record keeping
+- Development and testing
+
+### Google Sheets (n8n-nodes-base.googleSheets)
+
+**Best for:** Collaboration, reporting, easy data sharing
+
+Advantages:
+- Familiar spreadsheet interface for non-technical users
+- Easy to share and collaborate on data
+- Built-in visualization and formula capabilities
+- Good for reporting and dashboards
+- Accessible from anywhere
+
+When to use:
+- Data needs to be viewed/edited by multiple people
+- Non-technical users need access to data
+- Integration with other Google Workspace tools
+- Simple data structures without complex relationships
+- Workflow needs access to existing spreadsheets in Google Sheets
+
+Pitfalls:
+- API rate limits can affect high-volume workflows
+- Not suitable for frequently changing data
+- Performance degrades with very large datasets (>10k rows)
+
+### Airtable (n8n-nodes-base.airtable)
+
+**Best for:** Structured data with relationships, rich field types
+
+Advantages:
+- Supports relationships between tables
+- Rich field types (attachments, select, links, etc.)
+- Better structure than spreadsheets
+
+When to use:
+- Data has relationships or references between records
+- Need structured database-like features
+- Managing projects, tasks, or inventory
+- Workflow needs access to existing data in Airtable
+
+Pitfalls:
+- Requires Airtable account and API key
+- Schema changes require careful planning
+
+## Storage Patterns
+
+### Immediate Storage Pattern
+
+Store data immediately after collection or generation:
+
+\`\`\`mermaid
+flowchart LR
+    Trigger --> Process_Data["Process Data"]
+    Process_Data --> Storage_Node["Storage Node"]
+    Storage_Node --> Continue_Workflow["Continue Workflow"]
+\`\`\`
+
+Best for: Raw data preservation, audit trails, form submissions
+
+### Batch Storage Pattern
+
+Collect multiple items and store them together:
+
+\`\`\`mermaid
+flowchart LR
+    Trigger --> Loop_Split["Loop/Split"]
+    Loop_Split --> Process["Process"]
+    Process --> Aggregate["Aggregate"]
+    Aggregate --> Storage_Node["Storage Node"]
+\`\`\`
+
+Best for: Processing lists, batch operations, scheduled aggregations
+
+### Update Pattern
+
+Retrieve, modify, and update existing records:
+
+\`\`\`mermaid
+flowchart LR
+    Trigger --> Retrieve["Retrieve from Storage"]
+    Retrieve --> Modify["Modify"]
+    Modify --> Update_Storage["Update Storage Node"]
+\`\`\`
+
+Best for: Maintaining state, updating records, tracking changes
+
+### Lookup Pattern
+
+Query storage to retrieve specific records:
+
+\`\`\`mermaid
+flowchart LR
+    Trigger --> Query_Storage["Query Storage Node"]
+    Query_Storage --> Use_Data["Use Retrieved Data"]
+    Use_Data --> Continue_Workflow["Continue Workflow"]
+\`\`\`
+
+Best for: Enrichment, validation, conditional logic based on stored data
+
+## Key Considerations
+
+### Data Structure
+
+- **Plan your schema ahead:** Define what fields you need before creating storage
+- **Use consistent field names:** Match field names across your workflow for easy mapping
+- **Consider data types:** Ensure your storage supports the data types you need
+- **Think about relationships:** If data is related, consider Airtable or use multiple tables
+
+### Performance
+
+- **Batch operations when possible:** Multiple small writes are slower than batch operations
+- **Use appropriate operations:** Use "append" for new records, "update" for modifications
+- **Consider API limits:** Google Sheets has rate limits; plan accordingly for high-volume workflows
+
+### Data Integrity
+
+- **Store raw data first:** Keep unmodified input before transformations
+- **Handle errors gracefully:** Use error handling to prevent data loss on failures
+- **Validate before storing:** Ensure data quality before persistence
+- **Avoid duplicates:** Use unique identifiers or upsert operations when appropriate
+
+## Referencing Documents, Sheets, or Tables
+
+When configuring storage nodes, use ResourceLocator mode "list". This will allow users to select from existing documents, sheets, or tables rather than passing IDs dynamically.
+Use modes "id", "url" or "name" only when user specifically mentions it in their prompt.
+
+## Important Distinctions
+
+### Storage vs. Transformation
+
+- **Set/Merge nodes are NOT storage:** They transform data in memory only
+- **Storage happens explicitly:** Data won't persist unless you explicitly write it to storage
+
+### Temporary vs. Persistent Storage
+
+- **NOT covered by this technique:** Redis, caching, session storage, in-memory operations
+- **This technique covers:** Durable storage that persists beyond workflow execution
+- **Focus on permanence:** Use these nodes when you need data to survive restarts and be queryable later
+
+## Common Pitfalls to Avoid
+
+### Not Handling Duplicates
+
+Without proper unique identifiers or upsert logic, you may create duplicate records. Use unique IDs or check for existing records before inserting.
+
+### Ignoring Storage Limits
+
+Each storage system has limits (row counts, API rates, file sizes). Design your workflow to work within these constraints or implement pagination/batching.
+`;
+    }
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.DataPersistenceBestPractices = DataPersistenceBestPractices;
+//# sourceMappingURL=data-persistence.js.map

package/dist/prompts/best-practices/guides/data-persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-persistence.js","sourceRoot":"","sources":["../../../../src/prompts/best-practices/guides/data-persistence.ts"],"names":[],"mappings":";;;AACA,oCAA6C;AAE7C,MAAa,4BAA4B;IAAzC;QACU,cAAS,GAAG,yBAAiB,CAAC,gBAAgB,CAAC;QAC/C,YAAO,GAAG,OAAO,CAAC;QAEV,kBAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuLjC,CAAC;IAKF,CAAC;IAHA,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AAhMD,oEAgMC"}

package/dist/prompts/best-practices/guides/data-transformation.d.ts

@@ -0,0 +1,7 @@
+import type { BestPracticesDocument } from '../types';
+export declare class DataTransformationBestPractices implements BestPracticesDocument {
+    readonly technique: "data_transformation";
+    readonly version = "1.0.0";
+    private readonly documentation;
+    getDocumentation(): string;
+}

package/dist/prompts/best-practices/guides/data-transformation.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataTransformationBestPractices = void 0;
+const types_1 = require("../types");
+class DataTransformationBestPractices {
+    constructor() {
+        this.technique = types_1.WorkflowTechnique.DATA_TRANSFORMATION;
+        this.version = '1.0.0';
+        this.documentation = `# Best Practices: Data Transformation
+
+## Workflow Design
+
+### Core Principles
+- **Structure**: Always follow Input → Transform → Output pattern
+- **Optimization**: Filter and reduce data early to improve performance
+
+### Design Best Practices
+- Plan transformation requirements in plain language before building
+- Use Modular Design: Create reusable sub-workflows for common tasks like "Data Cleaning" or "Error Handler"
+- Batch datasets over 100 items using Split In Batches node to prevent timeouts
+
+## Recommended Nodes
+
+### Essential Transformation Nodes
+
+#### Edit Fields (Set) (n8n-nodes-base.set)
+
+**Purpose**: Create, modify, rename fields; change data types
+
+**Key Setting**: "Keep Only Set" - drops all fields not explicitly defined (default: disabled)
+
+**Use Cases**:
+- Extract specific columns
+- Add calculated fields
+- Convert data types (string to number)
+- Format dates using expressions
+
+**Pitfalls**:
+- Not understanding "Keep Only Set" behavior can lead to data loss
+- Enabled: Drops all fields not explicitly defined (data loss risk)
+- Disabled: Carries forward all fields (potential bloat)
+- Always verify output structure after configuration
+
+**Testing tip**: When transforming data from a workflow trigger, you can set values with a fallback default e.g. set name to {{$json.name || 'Jane Doe'}} to help test the workflow.
+
+#### IF/Filter Nodes
+
+**IF Node** (n8n-nodes-base.if):
+- **Purpose**: Conditional processing and routing
+- **Best Practice**: Use early to validate inputs and remove bad data
+- **Example**: Check if required fields exist before processing
+
+**Filter Node** (n8n-nodes-base.filter):
+- **Purpose**: Filter items based on conditions
+- **Best Practice**: Use early in workflow to reduce data volume
+
+#### Merge Node (n8n-nodes-base.merge)
+
+**Purpose**: Combine two data streams
+
+**Modes**:
+- Merge by Key (like database join)
+- Merge by Index
+- Append
+
+**Pitfalls**:
+- **Missing Keys**: Trying to merge on non-existent fields
+- **Field Name Mismatch**: Different field names in sources
+- **Solution**: Use Edit Fields node to normalize field names before merging
+
+#### Code Node (n8n-nodes-base.code)
+
+**Execution Modes**:
+- "Run Once per Item": Process each item independently
+- "Run Once for All Items": Access entire dataset (for aggregation)
+
+**Return Format**: Must return array of objects with json property
+\`\`\`javascript
+return items; // or return [{ json: {...} }];
+\`\`\`
+
+**Pitfalls**:
+- Wrong return format: Not returning array of objects with json property
+- Overly complex: Stuffing entire workflow logic in one Code node
+- Keep code nodes focused on single transformation aspect
+
+#### Summarize Node (n8n-nodes-base.summarize)
+
+**Purpose**: Pivot table-style aggregations (count, sum, average, min/max)
+
+**Configuration**:
+- Fields to Summarize: Choose aggregation function
+- Fields to Split By: Grouping keys
+
+**Output**: Single item with summary or multiple items per group
+
+### Data Restructuring Nodes
+
+- **Split Out** (n8n-nodes-base.splitOut): Convert single item with array into multiple items
+- **Aggregate** (n8n-nodes-base.aggregate): Combine multiple items into one
+- **Remove Duplicates** (n8n-nodes-base.removeDuplicates): Delete duplicate items based on field criteria
+- **Sort** (n8n-nodes-base.sort): Order items alphabetically/numerically
+- **Limit** (n8n-nodes-base.limit): Trim to maximum number of items
+
+### Batch Processing
+
+**Split In Batches** (n8n-nodes-base.splitInBatches):
+- **Purpose**: Process large datasets in chunks
+- **Use When**: Handling 100+ items with expensive operations (API calls, AI)
+
+## Input Data Validation
+- Validate external data before processing: check for nulls, empty values, and edge cases (special chars, empty arrays)
+
+## Common Pitfalls to Avoid
+
+### Critical Mistakes
+
+#### Edit Fields Node Issues
+- **Mistake**: Not understanding "Keep Only Set" behavior
+  - Enabled: Drops all fields not explicitly defined (data loss risk)
+  - Disabled: Carries forward all fields (potential bloat)
+- **Solution**: Always verify output structure after configuration
+
+#### Code Node Errors
+- **Wrong Return Format**: Not returning array of objects with json property
+- **Fix**: Always return \`items\` or \`[{ json: {...} }]\`
+- **Overly Complex**: Stuffing entire workflow logic in one Code node
+- **Fix**: Keep code nodes focused on single transformation aspect
+
+#### Merge Node Problems
+- **Field Name Mismatch**: Different field names in sources
+- **Fix**: Normalize field names with Edit Fields before merging
+
+### Performance Pitfalls
+- Processing large datasets without batching → timeouts
+- Not filtering early → unnecessary processing overhead
+- Excessive node chaining → visual clutter and slow execution
+
+### Data Validation Pitfalls
+- Assuming input data is always perfect → runtime errors
+`;
+    }
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.DataTransformationBestPractices = DataTransformationBestPractices;
+//# sourceMappingURL=data-transformation.js.map

package/dist/prompts/best-practices/guides/data-transformation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-transformation.js","sourceRoot":"","sources":["../../../../src/prompts/best-practices/guides/data-transformation.ts"],"names":[],"mappings":";;;AACA,oCAA6C;AAE7C,MAAa,+BAA+B;IAA5C;QACU,cAAS,GAAG,yBAAiB,CAAC,mBAAmB,CAAC;QAClD,YAAO,GAAG,OAAO,CAAC;QAEV,kBAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoIjC,CAAC;IAKF,CAAC;IAHA,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AA7ID,0EA6IC"}

package/dist/prompts/best-practices/guides/document-processing.d.ts

@@ -0,0 +1,7 @@
+import type { BestPracticesDocument } from '../types';
+export declare class DocumentProcessingBestPractices implements BestPracticesDocument {
+    readonly technique: "document_processing";
+    readonly version = "1.0.0";
+    private readonly documentation;
+    getDocumentation(): string;
+}