@jungvonmatt/contentful-ssg 1.4.9 → 1.7.3

package/README.md

@@ -209,6 +209,33 @@ Get values from linked pages to e.g. build an url out of parent slugs.
 
 The same as collectValues just without the value from the current entry
 
+###### waitFor
+
+Wait for specific entry to be transformed.
+Be aware that this can lead to deadlocks when you're awaiting something which
+itself is waiting for the current entry to be transformed.
+
+```js
+{
+  transform: (context) => {
+    const { utils } = context;
+    try {
+      // You can overwrite the default wait timeout of 20000ms using the second parameter
+      const linkedContext = await utils.waitFor('<contentful-id>', 5000);
+
+      // Do something usefull with the transformed data
+      // which you can't do with context.entryMap.get('<contentful-id>')
+
+    } catch (error) {
+      // Entry isn't available, the transform method for the entry throws an error
+      // or we encountered a cyclic dependency
+    }
+
+    return { ...content };
+  };
+}
+```
+
 ### fetch
 
 Fetch all content entries and store them as yaml in the configured directory

package/dist/index.js

@@ -1,4 +1,5 @@
 import Listr from 'listr';
+import { ReplaySubject } from 'rxjs';
 import chalk from 'chalk';
 import { getContentTypeId, getContentId } from './lib/contentful.js';
 import { setup } from './tasks/setup.js';
@@ -6,7 +7,7 @@ import { fetch } from './tasks/fetch.js';
 import { localize } from './tasks/localize.js';
 import { transform } from './tasks/transform.js';
 import { write } from './tasks/write.js';
-import { collectParentValues, collectValues } from './lib/utils.js';
+import { collectParentValues, collectValues, waitFor } from './lib/utils.js';
 import { ValidationError } from './lib/error.js';
 class CustomListrRenderer {
     _tasks;
@@ -63,6 +64,8 @@ export const run = async (config) => {
                 const tasks = locales.map((locale) => ({
                     title: `${locale.code}`,
                     task: async () => {
+                        const subject = new ReplaySubject();
+                        const observable = subject.asObservable();
                         const data = ctx.localized.get(locale.code);
                         const { entries = [] } = data || {};
                         const promises = entries.map(async (entry) => {
@@ -71,6 +74,7 @@ export const run = async (config) => {
                             const utils = {
                                 collectValues: collectValues({ ...data, entry }),
                                 collectParentValues: collectParentValues({ ...data, entry }),
+                                waitFor: waitFor({ ...data, entry, observable }),
                             };
                             const transformContext = {
                                 ...data,
@@ -79,9 +83,11 @@ export const run = async (config) => {
                                 entry,
                                 locale,
                                 utils,
+                                observable,
                             };
                             try {
                                 const content = await transform(transformContext, ctx, config);
+                                subject.next({ ...transformContext, content });
                                 if (typeof content === 'undefined') {
                                     return;
                                 }
@@ -89,10 +95,16 @@ export const run = async (config) => {
                                 ctx.stats.addSuccess(transformContext);
                             }
                             catch (error) {
+                                if (error instanceof Error) {
+                                    subject.next({ ...transformContext, error });
+                                }
+                                else {
+                                    subject.next({ ...transformContext, error: new Error(`${error}`) });
+                                }
                                 if (error instanceof ValidationError) {
                                     ctx.stats.addSkipped(transformContext, error);
                                 }
-                                else if (typeof error === 'string' || error instanceof Error) {
+                                else {
                                     ctx.stats.addError(transformContext, error);
                                 }
                             }

package/dist/lib/error.d.ts

@@ -7,3 +7,7 @@ export declare class ValidationError extends Error {
     locale: string;
     constructor(entry: ErrorEntry);
 }
+export declare class WrappedError extends Error {
+    originalError: unknown;
+    constructor(message: string, error: unknown);
+}

package/dist/lib/error.js

@@ -15,3 +15,11 @@ export class ValidationError extends Error {
         this.name = 'ValidationError';
     }
 }
+export class WrappedError extends Error {
+    originalError;
+    constructor(message, error) {
+        super(message);
+        this.originalError = error;
+        this.name = 'WrappedError';
+    }
+}

package/dist/lib/stats.d.ts

@@ -12,7 +12,7 @@ export declare class Stats {
         contentTypeId: string;
     };
     addSuccess(context: TransformContext, message?: string): void;
-    addError(context: TransformContext, error: string | Error): void;
+    addError(context: TransformContext, error: unknown): void;
     addSkipped(context: TransformContext, error: ValidationError): void;
     print(): Promise<void>;
 }

package/dist/lib/stats.js

@@ -21,11 +21,11 @@ export class Stats {
         this.success.push({ message, ...this.toEntry(context) });
     }
     addError(context, error) {
-        if (typeof error === 'string') {
-            this.errors.push({ error: new Error(error), ...this.toEntry(context) });
+        if (error instanceof Error) {
+            this.errors.push({ error, ...this.toEntry(context) });
         }
         else {
-            this.errors.push({ error, ...this.toEntry(context) });
+            this.errors.push({ error: new Error(`${error}`), ...this.toEntry(context) });
         }
     }
     addSkipped(context, error) {

package/dist/lib/utils.d.ts

@@ -2,3 +2,4 @@ import type { CollectOptions, Entry, TransformContext } from '../types.js';
 export declare const collectValues: (transformContext: Pick<TransformContext, 'entry' | 'entryMap'>) => (key: any, options?: CollectOptions) => any[];
 export declare const collectParentValues: (transformContext: Pick<TransformContext, 'entry' | 'entryMap'>) => (key: any, options?: CollectOptions) => any[];
 export declare const collect: <T = unknown>(entry: Entry, entryMap: Map<string, Entry>, options: CollectOptions) => T[];
+export declare const waitFor: (transformContext: Pick<TransformContext, 'entry' | 'observable' | 'entryMap'>) => (id: string, waitTimeout?: number) => Promise<unknown>;

package/dist/lib/utils.js

@@ -1,4 +1,8 @@
+import { getContentId, getContentTypeId } from './contentful.js';
+import { ReplaySubject, map, distinct, filter } from 'rxjs';
 import dlv from 'dlv';
+import { WrappedError } from './error.js';
+const DEFAULT_WAIT_TIMEOUT = 20000;
 export const collectValues = (transformContext) => (key, options) => {
     const { entry: defaultEntry, entryMap: defaultEntryMap } = transformContext;
     const { getNextId, linkField, entry = defaultEntry, entryMap = defaultEntryMap, } = options || {};
@@ -29,3 +33,73 @@ export const collect = (entry, entryMap, options) => {
     }
     return [value];
 };
+const dependencies = {};
+const buildDependencies = (v) => {
+    if ((dependencies?.[v.source] ?? []).includes(v.dest)) {
+        return dependencies;
+    }
+    if (dependencies[v.source]) {
+        dependencies[v.source] = [...dependencies[v.source], v.dest];
+    }
+    else {
+        dependencies[v.source] = [v.dest];
+    }
+    Object.entries({ ...dependencies })
+        .filter(([, value]) => value.includes(v.source))
+        .forEach(([key, value]) => {
+        dependencies[key] = [...new Set([...value, v.dest, ...(dependencies[v.dest] || [])])];
+    });
+    return dependencies;
+};
+const waitForSubject = new ReplaySubject();
+const cyclicErrorObservable = waitForSubject
+    .asObservable()
+    .pipe(map((value) => buildDependencies(value)));
+export const waitFor = (transformContext) => {
+    const sourceEntry = transformContext.entry;
+    const sourceId = getContentId(sourceEntry);
+    const sourceContentTypeId = getContentTypeId(sourceEntry);
+    const source = `${sourceId} (${sourceContentTypeId})`;
+    return async (id, waitTimeout = DEFAULT_WAIT_TIMEOUT) => {
+        if (sourceId === id) {
+            throw new Error(`Can't wait for yourself.
+Entry ${source} waiting for ${source}.`);
+        }
+        waitForSubject.next({ source: getContentId(sourceEntry), dest: id });
+        const destEntry = transformContext.entryMap.get(id);
+        const destId = getContentId(destEntry);
+        const destContentTypeId = getContentTypeId(destEntry);
+        const dest = `${destId} (${destContentTypeId})`;
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                reject(new Error(`Exceeded timeout of ${waitTimeout} ms while waiting for entry ${id} to complete.
+Entry ${source} waiting for ${dest}.`));
+            }, waitTimeout);
+            if (transformContext.entryMap.has(id)) {
+                transformContext.observable
+                    .pipe(filter((ctx) => ctx?.entry?.sys?.id === id))
+                    .subscribe((value) => {
+                    clearTimeout(timeout);
+                    if (value.error) {
+                        reject(new WrappedError(`Awaited entry ${dest} errored`, value.error));
+                    }
+                    else {
+                        resolve(value);
+                    }
+                });
+                cyclicErrorObservable
+                    .pipe(filter((v) => v?.[sourceId]?.includes(sourceId)))
+                    .pipe(distinct())
+                    .subscribe((v) => {
+                    clearTimeout(timeout);
+                    const deps = v?.[sourceId] ?? [];
+                    reject(new Error(`Found cyclic dependency in ${source}: ${[sourceId, ...deps].join(' -> ')}`));
+                });
+            }
+            else {
+                clearTimeout(timeout);
+                reject(new Error(`No entry with id "${id}" available`));
+            }
+        });
+    };
+};

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { Options } from '@contentful/rich-text-html-renderer';
 import type { Document } from '@contentful/rich-text-types';
+import type { Observable } from 'rxjs';
 import type { QueryOptions, CollectionProp } from 'contentful-management/types';
 import type { EntryFields, Locale as ContentfulLocale, Asset as ContentfulAsset, Field, Entry as ContentfulEntry, ContentType as ContentfulContentType } from 'contentful';
 import type { ListrTaskObject } from 'listr';
@@ -131,6 +132,7 @@ export declare type Task = ListrTaskObject<RuntimeContext>;
 export interface TransformHelper {
     collectValues: <T>(key: any, options?: CollectOptions) => T[];
     collectParentValues: <T>(key: any, options?: CollectOptions) => T[];
+    waitFor: (id: string, waitTimeout?: number) => Promise<ObservableContext>;
 }
 export declare type TransformContext = LocalizedContent & {
     [x: string]: any;
@@ -145,7 +147,11 @@ export declare type TransformContext = LocalizedContent & {
     fieldSettings?: Field;
     requiredFields?: string[];
     utils: TransformHelper;
+    observable: Observable<ObservableContext>;
 };
+export declare type ObservableContext = Readonly<Pick<TransformContext, 'id' | 'contentTypeId' | 'entry' | 'content' | 'locale'> & {
+    error?: Error;
+}>;
 export interface Ignore {
     add(pattern: string | Ignore | string[] | Ignore[]): Ignore;
     filter(paths: string[]): string[];

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "@jungvonmatt/contentful-ssg",
-  "version": "1.4.9",
+  "version": "1.7.3",
   "description": "",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jungvonmatt/contentful-ssg.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jungvonmatt/contentful-ssg/issues"
+  },
   "main": "./dist/index.js",
   "type": "module",
   "typings": "./dist/types.d.ts",
@@ -118,6 +125,7 @@
     "micromatch": "^4.0.4",
     "prettier": "^2.4.1",
     "read-pkg-up": "^9.0.0",
+    "rxjs": "^7.5.5",
     "slash": "^4.0.0",
     "snake-case": "^3.0.4",
     "tempy": "^2.0.0",
@@ -155,5 +163,5 @@
       "module": "es2020"
     }
   },
-  "gitHead": "17ccdcf1aedc0eea54740aa71279e5bd1cb77699"
+  "gitHead": "07c6810f528dc8cf51fad3f8e8cc6081facd9232"
 }

package/src/index.ts

@@ -1,5 +1,13 @@
-import type { Config, RuntimeContext, Task, TransformContext, TransformHelper } from './types.js';
+import type {
+  Config,
+  ObservableContext,
+  RuntimeContext,
+  Task,
+  TransformContext,
+  TransformHelper,
+} from './types.js';
 import Listr from 'listr';
+import { ReplaySubject } from 'rxjs';
 import chalk from 'chalk';
 import { getContentTypeId, getContentId } from './lib/contentful.js';
 import { setup } from './tasks/setup.js';
@@ -7,7 +15,7 @@ import { fetch } from './tasks/fetch.js';
 import { localize } from './tasks/localize.js';
 import { transform } from './tasks/transform.js';
 import { write } from './tasks/write.js';
-import { collectParentValues, collectValues } from './lib/utils.js';
+import { collectParentValues, collectValues, waitFor } from './lib/utils.js';
 import { ValidationError } from './lib/error.js';
 
 /**
@@ -83,6 +91,8 @@ export const run = async (config: Config): Promise<void> => {
           const tasks = locales.map((locale) => ({
             title: `${locale.code}`,
             task: async () => {
+              const subject = new ReplaySubject<ObservableContext>();
+              const observable = subject.asObservable();
               const data = ctx.localized.get(locale.code);
               const { entries = [] } = data || {};
 
@@ -94,6 +104,7 @@ export const run = async (config: Config): Promise<void> => {
                 const utils = {
                   collectValues: collectValues({ ...data, entry }),
                   collectParentValues: collectParentValues({ ...data, entry }),
+                  waitFor: waitFor({ ...data, entry, observable }),
                 } as TransformHelper;
 
                 const transformContext: TransformContext = {
@@ -103,10 +114,12 @@ export const run = async (config: Config): Promise<void> => {
                   entry,
                   locale,
                   utils,
+                  observable,
                 };
 
                 try {
                   const content = await transform(transformContext, ctx, config);
+                  subject.next({ ...transformContext, content });
 
                   if (typeof content === 'undefined') {
                     return;
@@ -115,9 +128,16 @@ export const run = async (config: Config): Promise<void> => {
                   await write({ ...transformContext, content }, ctx, config);
                   ctx.stats.addSuccess(transformContext);
                 } catch (error: unknown) {
+                  if (error instanceof Error) {
+                    subject.next({ ...transformContext, error });
+                  } else {
+                    // eslint-disable-next-line @typescript-eslint/no-base-to-string, @typescript-eslint/restrict-template-expressions
+                    subject.next({ ...transformContext, error: new Error(`${error}`) });
+                  }
+
                   if (error instanceof ValidationError) {
                     ctx.stats.addSkipped(transformContext, error);
-                  } else if (typeof error === 'string' || error instanceof Error) {
+                  } else {
                     ctx.stats.addError(transformContext, error);
                   }
                 }

package/src/lib/error.ts

@@ -17,3 +17,13 @@ export class ValidationError extends Error {
     this.name = 'ValidationError';
   }
 }
+
+export class WrappedError extends Error {
+  originalError: unknown;
+
+  constructor(message: string, error: unknown) {
+    super(message);
+    this.originalError = error;
+    this.name = 'WrappedError';
+  }
+}

package/src/lib/stats.ts

@@ -28,11 +28,12 @@ export class Stats {
     this.success.push({ message, ...this.toEntry(context) });
   }
 
-  addError(context: TransformContext, error: string | Error): void {
-    if (typeof error === 'string') {
-      this.errors.push({ error: new Error(error), ...this.toEntry(context) });
-    } else {
+  addError(context: TransformContext, error: unknown): void {
+    if (error instanceof Error) {
       this.errors.push({ error, ...this.toEntry(context) });
+    } else {
+      // eslint-disable-next-line @typescript-eslint/no-base-to-string, @typescript-eslint/restrict-template-expressions
+      this.errors.push({ error: new Error(`${error}`), ...this.toEntry(context) });
     }
   }
 

package/src/lib/utils.test.ts

@@ -1,5 +1,7 @@
 import { Entry, TransformContext } from '../types.js';
-import { collect, collectParentValues, collectValues } from './utils.js';
+import { collect, collectParentValues, collectValues, waitFor } from './utils.js';
+import { ReplaySubject } from 'rxjs';
+import { WrappedError } from './error.js';
 
 const data = new Map([
   ['1', { sys: { id: '1' }, fields: { slug: 'a' } }],
@@ -9,12 +11,66 @@ const data = new Map([
   ['5', { sys: { id: '5' }, fields: { slug: 'e', parent: '4' } }],
 ]) as unknown as Map<string, Entry>;
 
+const contentType = { sys: { id: 'test-type' } };
+
 const entryMap = new Map([
-  ['1', { sys: { id: '1' }, fields: { slug: 'a' } }],
-  ['2', { sys: { id: '2' }, fields: { slug: 'b', parent: { sys: { id: '1' } }, link: { sys: { id: '1' } } } }],
-  ['3', { sys: { id: '3' }, fields: { slug: 'c', parent: { sys: { id: '2' } }, link: { sys: { id: '1' } } } }],
-  ['4', { sys: { id: '4' }, fields: { slug: 'd', parent: { sys: { id: '3' } }, link: { sys: { id: '3' } } } }],
-  ['5', { sys: { id: '5' }, fields: { slug: 'e', parent: { sys: { id: '4' } }, link: { sys: { id: '3' } } } }],
+  ['1', { sys: { id: '1', contentType }, fields: { slug: 'a' } }],
+  [
+    '2',
+    {
+      sys: { id: '2', contentType },
+      fields: { slug: 'b', parent: { sys: { id: '1' } }, link: { sys: { id: '1' } } },
+    },
+  ],
+  [
+    '3',
+    {
+      sys: { id: '3', contentType },
+      fields: { slug: 'c', parent: { sys: { id: '2' } }, link: { sys: { id: '1' } } },
+    },
+  ],
+  [
+    '4',
+    {
+      sys: { id: '4', contentType },
+      fields: { slug: 'd', parent: { sys: { id: '3' } }, link: { sys: { id: '3' } } },
+    },
+  ],
+  [
+    '5',
+    {
+      sys: { id: '5', contentType },
+      fields: { slug: 'e', parent: { sys: { id: '4' } }, link: { sys: { id: '3' } } },
+    },
+  ],
+  [
+    '6',
+    {
+      sys: { id: '6', contentType },
+      fields: { slug: 'f', parent: { sys: { id: '1' } }, link: { sys: { id: '1' } } },
+    },
+  ],
+  [
+    '7',
+    {
+      sys: { id: '7', contentType },
+      fields: { slug: 'g', parent: { sys: { id: '2' } }, link: { sys: { id: '1' } } },
+    },
+  ],
+  [
+    '8',
+    {
+      sys: { id: '8', contentType },
+      fields: { slug: 'h', parent: { sys: { id: '3' } }, link: { sys: { id: '3' } } },
+    },
+  ],
+  [
+    '9',
+    {
+      sys: { id: '9', contentType },
+      fields: { slug: 'i', parent: { sys: { id: '4' } }, link: { sys: { id: '3' } } },
+    },
+  ],
 ]) as unknown as Map<string, Entry>;
 
 const transformContext = { entryMap } as unknown as TransformContext;
@@ -82,4 +138,161 @@ describe('Utils', () => {
     expect(a).toEqual(['a', 'b', 'c', 'd', 'e']);
     expect(b).toEqual(['e', 'd', 'c', 'b', 'a']);
   });
+
+  test('waitFor', async () => {
+    const subject = new ReplaySubject<TransformContext>(null);
+    const observable = subject.asObservable();
+
+    // Throw error when waiting for the current entry
+    expect(async () => {
+      await waitFor({ ...transformContext, entry: entryMap.get('2'), observable })('2');
+    }).rejects.toThrowError(/2.*waiting.*2/);
+
+    // Throw error when waiting for non existing entry
+    expect(async () => {
+      await waitFor({ ...transformContext, entry: entryMap.get('3'), observable })('10');
+    }).rejects.toThrowError('No entry with id "10" available');
+
+    // // Throw error when waiting timeout is reached
+    await expect(async () => {
+      await waitFor({ ...transformContext, entry: entryMap.get('1'), observable })('4', 50);
+    }).rejects.toThrowError(/Exceeded timeout of 50 ms/);
+
+    // Mimic 500ms wait time for entry
+    setTimeout(() => {
+      subject.next({ ...transformContext, entry: entryMap.get('4'), observable });
+    }, 500);
+
+    const value = await waitFor({ ...transformContext, entry: entryMap.get('1'), observable })('4');
+    expect(value).toEqual({ ...transformContext, entry: entryMap.get('4'), observable });
+  });
+
+  test('waitFor error', async () => {
+    const subject = new ReplaySubject<TransformContext>(null);
+    const observable = subject.asObservable();
+    const entry = entryMap.get('3');
+
+    // Mimic 500ms wait time for entry
+    setTimeout(() => {
+      subject.next({
+        ...transformContext,
+        entry: entryMap.get('4'),
+        observable,
+        error: new Error('test error'),
+      });
+    }, 500);
+
+    await expect(async () => {
+      await waitFor({ ...transformContext, entry, observable })('4');
+    }).rejects.toThrowError(WrappedError);
+
+    try {
+      await waitFor({ ...transformContext, entry, observable })('4');
+    } catch (error) {
+      expect(error).toBeInstanceOf(WrappedError);
+      expect(error.message).toMatch('Awaited entry 4 (test-type) errored');
+      expect(error.originalError.message).toEqual('test error');
+    }
+  });
+
+  test('detect cyclic dependency', async () => {
+    const subject = new ReplaySubject<TransformContext>(null);
+    const observable = subject.asObservable();
+
+    // let 9 finish regularly
+    setTimeout(() => {
+      subject.next({
+        ...transformContext,
+        entry: entryMap.get('9'),
+        observable,
+      });
+    }, 100);
+
+    // mimic behaviour in index.ts
+    const waitMock = async (source: string, dest: string, delay: number) => {
+      await new Promise((resolve) => setTimeout(resolve, delay));
+      try {
+        await waitFor({ ...transformContext, entry: entryMap.get(source), observable })(dest, 1000);
+        subject.next({
+          ...transformContext,
+          entry: entryMap.get(source),
+          observable,
+        });
+        return `SUCCESS ${source}`;
+      } catch (error) {
+        subject.next({
+          ...transformContext,
+          entry: entryMap.get(source),
+          error,
+          observable,
+        });
+        return `${error.message}`;
+      }
+    };
+
+    const result = await Promise.all([
+      waitMock('6', '8', 0),
+      waitMock('8', '5', 10),
+      waitMock('5', '7', 20),
+      waitMock('7', '6', 30),
+      waitMock('3', '9', 40),
+    ]);
+
+    expect(result[0]).toMatch('Found cyclic dependency in 6 (test-type): 6 -> 8 -> 5 -> 7 -> 6');
+    expect(result[1]).toMatch('Found cyclic dependency in 8 (test-type): 8 -> 5 -> 7 -> 6 -> 8');
+    expect(result[2]).toMatch('Found cyclic dependency in 5 (test-type): 5 -> 7 -> 6 -> 8 -> 5');
+    expect(result[3]).toMatch(/Awaited entry 6 \(test-type\) errored/);
+    expect(result[4]).toMatch('SUCCESS 3');
+  });
+
+  test('handle subscriptions on postponed subscribe', async () => {
+    const subject = new ReplaySubject<TransformContext>();
+    const observable = subject.asObservable();
+
+    const finishSuccess = (id, time = 0) =>
+      setTimeout(() => {
+        subject.next({
+          ...transformContext,
+          entry: entryMap.get(id),
+          observable,
+        });
+      }, time);
+
+    const finishError = (id, time = 0) =>
+      setTimeout(() => {
+        subject.next({
+          ...transformContext,
+          entry: entryMap.get(id),
+          error: new Error(`Error on ${id}`),
+          observable,
+        });
+      }, time);
+
+    finishSuccess('2', 20);
+    finishSuccess('3', 40);
+    finishError('4', 30);
+    finishSuccess('5', 50);
+
+    const transFormMock = () =>
+      Promise.all([
+        waitFor({ ...transformContext, entry: entryMap.get('1'), observable })('2'),
+        waitFor({ ...transformContext, entry: entryMap.get('1'), observable })('3'),
+        waitFor({ ...transformContext, entry: entryMap.get('1'), observable })('4'),
+        waitFor({ ...transformContext, entry: entryMap.get('1'), observable })('5'),
+      ]);
+
+    const result = await new Promise((resolve) => {
+      setTimeout(async () => {
+        try {
+          const result = await transFormMock();
+          resolve(result);
+        } catch (error) {
+          resolve(error);
+        }
+      }, 500);
+    });
+
+    expect(result).toBeInstanceOf(WrappedError);
+    expect((result as WrappedError).message).toMatch(/Awaited entry 4 \(test-type\) errored/);
+  });
 });

package/src/lib/utils.ts

@@ -1,5 +1,11 @@
 import type { CollectOptions, Entry, TransformContext } from '../types.js';
+import { getContentId, getContentTypeId } from './contentful.js';
+import { ReplaySubject, map, distinct, filter } from 'rxjs';
 import dlv from 'dlv';
+import { WrappedError } from './error.js';
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const DEFAULT_WAIT_TIMEOUT = 20000;
 
 export const collectValues =
   (transformContext: Pick<TransformContext, 'entry' | 'entryMap'>) =>
@@ -55,3 +61,96 @@ export const collect = <T = unknown>(
 
   return [value];
 };
+
+const dependencies: Record<string, string[]> = {};
+
+const buildDependencies = (v: { source: string; dest: string }) => {
+  if ((dependencies?.[v.source] ?? []).includes(v.dest)) {
+    return dependencies;
+  }
+
+  if (dependencies[v.source]) {
+    dependencies[v.source] = [...dependencies[v.source], v.dest];
+  } else {
+    dependencies[v.source] = [v.dest];
+  }
+
+  Object.entries({ ...dependencies })
+    .filter(([, value]) => value.includes(v.source))
+    .forEach(([key, value]) => {
+      dependencies[key] = [...new Set([...value, v.dest, ...(dependencies[v.dest] || [])])];
+    });
+
+  return dependencies;
+};
+
+const waitForSubject = new ReplaySubject<{ source: string; dest: string }>();
+
+const cyclicErrorObservable = waitForSubject
+  .asObservable()
+  .pipe(map((value) => buildDependencies(value)));
+
+/**
+ * Wait for entry to be transformed
+ */
+export const waitFor = (
+  transformContext: Pick<TransformContext, 'entry' | 'observable' | 'entryMap'>
+) => {
+  const sourceEntry = transformContext.entry;
+  const sourceId = getContentId(sourceEntry);
+  const sourceContentTypeId = getContentTypeId(sourceEntry);
+  const source = `${sourceId} (${sourceContentTypeId})`;
+
+  return async (id: string, waitTimeout = DEFAULT_WAIT_TIMEOUT) => {
+    // Make sure we don't try to wait for the current entry
+    if (sourceId === id) {
+      throw new Error(`Can't wait for yourself.
+Entry ${source} waiting for ${source}.`);
+    }
+
+    waitForSubject.next({ source: getContentId(sourceEntry), dest: id });
+    const destEntry = transformContext.entryMap.get(id);
+    const destId = getContentId(destEntry);
+    const destContentTypeId = getContentTypeId(destEntry);
+    const dest = `${destId} (${destContentTypeId})`;
+
+    return new Promise((resolve, reject) => {
+      // If anything goes wrong, reject promise after waitTimeout
+      const timeout = setTimeout(() => {
+        reject(
+          new Error(
+            `Exceeded timeout of ${waitTimeout} ms while waiting for entry ${id} to complete.
+Entry ${source} waiting for ${dest}.`
+          )
+        );
+      }, waitTimeout);
+
+      if (transformContext.entryMap.has(id)) {
+        transformContext.observable
+          .pipe(filter((ctx) => ctx?.entry?.sys?.id === id))
+          .subscribe((value) => {
+            clearTimeout(timeout);
+            if (value.error) {
+              reject(new WrappedError(`Awaited entry ${dest} errored`, value.error));
+            } else {
+              resolve(value);
+            }
+          });
+
+        cyclicErrorObservable
+          .pipe(filter((v) => v?.[sourceId]?.includes(sourceId)))
+          .pipe(distinct())
+          .subscribe((v) => {
+            clearTimeout(timeout);
+            const deps = v?.[sourceId] ?? [];
+            reject(
+              new Error(`Found cyclic dependency in ${source}: ${[sourceId, ...deps].join(' -> ')}`)
+            );
+          });
+      } else {
+        clearTimeout(timeout);
+        reject(new Error(`No entry with id "${id}" available`));
+      }
+    });
+  };
+};

package/src/types.ts

@@ -1,5 +1,6 @@
 import type { Options } from '@contentful/rich-text-html-renderer';
 import type { Document } from '@contentful/rich-text-types';
+import type { Observable } from 'rxjs';
 import type { QueryOptions, CollectionProp } from 'contentful-management/types';
 
 import type {
@@ -202,6 +203,7 @@ export type Task = ListrTaskObject<RuntimeContext>;
 export interface TransformHelper {
   collectValues: <T>(key, options?: CollectOptions) => T[];
   collectParentValues: <T>(key, options?: CollectOptions) => T[];
+  waitFor: (id: string, waitTimeout?: number) => Promise<ObservableContext>;
 }
 
 export type TransformContext = LocalizedContent & {
@@ -217,8 +219,14 @@ export type TransformContext = LocalizedContent & {
   fieldSettings?: Field;
   requiredFields?: string[];
   utils: TransformHelper;
+  observable: Observable<ObservableContext>;
 };
 
+export type ObservableContext = Readonly<
+  Pick<TransformContext, 'id' | 'contentTypeId' | 'entry' | 'content' | 'locale'> & {
+    error?: Error;
+  }
+>;
 export interface Ignore {
   add(pattern: string | Ignore | string[] | Ignore[]): Ignore;
   filter(paths: string[]): string[];