OpenNoodl/dev-docs/tasks/phase-11-cloud-functions/CF11-003-wait-delay-nodes/README.md

CF11-003: Wait/Delay Nodes

Metadata

Field	Value
ID	CF11-003
Phase	Phase 11
Series	1 - Advanced Workflow Nodes
Priority	🟢 Medium
Difficulty	🟢 Low
Estimated Time	4-6 hours
Prerequisites	Phase 5 TASK-007C (Workflow Runtime)
Branch	feature/cf11-003-delay-nodes

Objective

Create timing-related workflow nodes: Wait for explicit delays, Wait Until for scheduled execution, and debounce utilities - essential for rate limiting and scheduled workflows.

Background

Workflows often need timing control:

• Wait: Pause execution for a duration (rate limiting APIs)
• Wait Until: Execute at a specific time (scheduled tasks)
• Debounce: Prevent rapid repeated execution

Scope

In Scope

• Wait Node (delay for X milliseconds)
• Wait Until Node (wait until specific time)
• Debounce Node (rate limit execution)

Out of Scope

• Cron scheduling (handled by triggers)
• Throttle node (future)

Technical Approach

Wait Node

const WaitNode = {
  name: 'Workflow Wait',
  displayName: 'Wait',
  category: 'Workflow Logic',

  inputs: {
    run: { type: 'signal' },
    duration: { type: 'number', displayName: 'Duration (ms)', default: 1000 },
    unit: {
      type: 'enum',
      options: ['milliseconds', 'seconds', 'minutes', 'hours'],
      default: 'milliseconds'
    }
  },

  outputs: {
    done: { type: 'signal', displayName: 'Done' }
  },

  async run(context) {
    let ms = context.inputs.duration || 1000;
    const unit = context.inputs.unit || 'milliseconds';

    // Convert to milliseconds
    const multipliers = {
      milliseconds: 1,
      seconds: 1000,
      minutes: 60 * 1000,
      hours: 60 * 60 * 1000
    };
    ms = ms * (multipliers[unit] || 1);

    await new Promise((resolve) => setTimeout(resolve, ms));
    context.triggerOutput('done');
  }
};

Wait Until Node

const WaitUntilNode = {
  name: 'Workflow Wait Until',
  displayName: 'Wait Until',
  category: 'Workflow Logic',

  inputs: {
    run: { type: 'signal' },
    targetTime: { type: 'string', displayName: 'Target Time (ISO)' },
    targetDate: { type: 'date', displayName: 'Target Date' }
  },

  outputs: {
    done: { type: 'signal' },
    skipped: { type: 'signal', displayName: 'Already Passed' }
  },

  async run(context) {
    const target = context.inputs.targetDate || new Date(context.inputs.targetTime);
    const now = Date.now();
    const targetMs = target.getTime();

    if (targetMs <= now) {
      // Time already passed
      context.triggerOutput('skipped');
      return;
    }

    const waitTime = targetMs - now;
    await new Promise((resolve) => setTimeout(resolve, waitTime));
    context.triggerOutput('done');
  }
};

Debounce Node

const DebounceNode = {
  name: 'Workflow Debounce',
  displayName: 'Debounce',
  category: 'Workflow Logic',

  inputs: {
    run: { type: 'signal' },
    delay: { type: 'number', default: 500 }
  },

  outputs: {
    trigger: { type: 'signal' }
  },

  setup(context) {
    context._debounceTimer = null;
  },

  run(context) {
    if (context._debounceTimer) {
      clearTimeout(context._debounceTimer);
    }

    context._debounceTimer = setTimeout(() => {
      context.triggerOutput('trigger');
      context._debounceTimer = null;
    }, context.inputs.delay || 500);
  }
};

Implementation Steps

1. Wait Node (2h) - Simple delay, unit conversion
2. Wait Until Node (2h) - Date parsing, time calculation
3. Debounce Node (1h) - Timer management
4. Testing (1h) - Unit tests

Success Criteria

• Wait delays for specified duration
• Wait supports multiple time units
• Wait Until triggers at target time
• Wait Until handles past times gracefully
• Debounce prevents rapid triggers

References

• CF11-001 Logic Nodes
• n8n Wait Node