Dependency Waves

1'use strict';
2
3// Interleaves a per-record producer with its dependents (media files and the products that show
4// them, a parent and its children), so a dependent batch starts as soon as its own producer
5// records are written instead of after the whole producer task. Pure: it reads no files and
6// decides nothing about readiness; gateBatch still checks every reference key on its own.
7//
8// dependents: [{ sourceStableKey, needs: [producerSourceKey, ...] }] in import order.
9// producerKeys: every producer key in its import order; keys no dependent needs go last.
10// Returns [{ producerKeys, dependentKeys }]: write each wave's producer keys, then its dependents.
11// A key two dependents share is written in the first wave that needs it. The final wave carries
12// the producer keys no dependent named, with no dependents.
13function planDependencyWaves({ dependents = [], producerKeys = [], waveSize = 50 } = {}) {
14  if (!Array.isArray(dependents) || !Array.isArray(producerKeys) || !Number.isInteger(waveSize) || waveSize < 1) throw new Error('DEPENDENCY_WAVES_INVALID');
15  const known = new Set(producerKeys), scheduled = new Set(), seen = new Set(), waves = [];
16  for (let start = 0; start < dependents.length; start += waveSize) {
17    const wave = { producerKeys: [], dependentKeys: [] };
18    for (const dependent of dependents.slice(start, start + waveSize)) {
19      if (!dependent || typeof dependent.sourceStableKey !== 'string' || seen.has(dependent.sourceStableKey) || !Array.isArray(dependent.needs)) throw new Error('DEPENDENCY_WAVES_INVALID');
20      seen.add(dependent.sourceStableKey); wave.dependentKeys.push(dependent.sourceStableKey);
21      // A key the producer does not have is left to the gate, which defers that dependent.
22      for (const key of dependent.needs) if (known.has(key) && !scheduled.has(key)) { scheduled.add(key); wave.producerKeys.push(key); }
23    }
24    waves.push(wave);
25  }
26  const rest = producerKeys.filter(key => !scheduled.has(key));
27  if (rest.length) waves.push({ producerKeys: [...new Set(rest)], dependentKeys: [] });
28  return waves;
29}
30
31module.exports = { planDependencyWaves };