@jungvonmatt/contentful-ssg 1.4.0 → 1.7.0

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
@@ -217,6 +244,11 @@ Fetch all content entries and store them as yaml in the configured directory
 npx cssg fetch
 ```
 
+To see all available command line options call
+```bash
+npx cssg help fetch
+```
+
 ## Example configuration
 
 ### Grow

package/dist/cli.js

@@ -14,10 +14,10 @@ import { getConfig, getEnvironmentConfig } from './lib/config.js';
 import { run } from './index.js';
 const env = dotenv.config();
 dotenvExpand(env);
-const parseArgs = (cmd) => ({
-    environment: cmd.env,
-    preview: Boolean(cmd.preview),
-    verbose: Boolean(cmd.verbose),
+const parseFetchArgs = (cmd) => ({
+    preview: cmd.preview,
+    verbose: cmd.verbose,
+    ignoreErrors: cmd.ignoreErrors,
 });
 const errorHandler = (error, silence) => {
     if (!silence) {
@@ -37,7 +37,7 @@ program
     .option('--typescript', 'Initialize typescript config')
     .action(actionRunner(async (cmd) => {
     const useTypescript = Boolean(cmd?.typescript ?? false);
-    const config = await getConfig(parseArgs(cmd || {}));
+    const config = await getConfig();
     const verified = await askAll(config);
     const environmentConfig = getEnvironmentConfig();
     const filePath = path.join(process.cwd(), `contentful-ssg.config.${useTypescript ? 'ts' : 'js'}`);
@@ -88,8 +88,9 @@ program
     .description('Fetch content objects')
     .option('-p, --preview', 'Fetch with preview mode')
     .option('-v, --verbose', 'Verbose output')
+    .option('--ignore-errors', 'No error return code when transform has errors')
     .action(actionRunner(async (cmd) => {
-    const config = await getConfig(parseArgs(cmd || {}));
+    const config = await getConfig(parseFetchArgs(cmd || {}));
     const verified = await askMissing(config);
     return run(verified);
 }));

package/dist/index.js

@@ -1,4 +1,5 @@
 import Listr from 'listr';
+import { BehaviorSubject } 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;
@@ -54,10 +55,7 @@ export const run = async (config) => {
         {
             title: 'Before Hook',
             skip: (ctx) => !ctx.hooks.has('before'),
-            task: async (ctx) => {
-                const result = await ctx.hooks.before();
-                ctx = { ...ctx, ...(result || {}) };
-            },
+            task: async (ctx) => ctx.hooks.before(),
         },
         {
             title: 'Writing files',
@@ -66,6 +64,8 @@ export const run = async (config) => {
                 const tasks = locales.map((locale) => ({
                     title: `${locale.code}`,
                     task: async () => {
+                        const subject = new BehaviorSubject(null);
+                        const observable = subject.asObservable();
                         const data = ctx.localized.get(locale.code);
                         const { entries = [] } = data || {};
                         const promises = entries.map(async (entry) => {
@@ -74,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,
@@ -82,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;
                                 }
@@ -92,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);
                                 }
                             }
@@ -109,10 +118,7 @@ export const run = async (config) => {
         {
             title: 'After Hook',
             skip: (ctx) => !ctx.hooks.has('after'),
-            task: async (ctx) => {
-                const result = await ctx.hooks.after();
-                ctx = { ...ctx, ...(result || {}) };
-            },
+            task: async (ctx) => ctx.hooks.after(),
         },
         {
             title: 'Cleanup',
@@ -122,4 +128,7 @@ export const run = async (config) => {
     const ctx = await tasks.run();
     await ctx.stats.print();
     console.log('\n---------------------------------------------');
+    if (ctx.stats.errors?.length && !config.ignoreErrors) {
+        process.exit(1);
+    }
 };

package/dist/lib/config.js

@@ -80,7 +80,7 @@ export const getEnvironmentConfig = (strict = true) => removeEmpty({
     previewAccessToken: process.env.CONTENTFUL_PREVIEW_TOKEN,
     accessToken: process.env.CONTENTFUL_DELIVERY_TOKEN,
 }, strict);
-export const getConfig = async (args) => {
+export const getConfig = async (args = {}) => {
     const defaultOptions = {
         environmentId: 'master',
         host: 'api.contentful.com',

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';
@@ -50,6 +51,7 @@ export declare type Config = Partial<ContentfulConfig> & Hooks & {
     directory: string;
     managedDirectories?: string[];
     verbose?: boolean;
+    ignoreErrors?: boolean;
     plugins?: Array<[string, KeyValueMap] | PluginInfo | string>;
     resolvedPlugins?: Hooks[];
     preset?: string;
@@ -130,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;
@@ -144,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,6 +1,6 @@
 {
   "name": "@jungvonmatt/contentful-ssg",
-  "version": "1.4.0",
+  "version": "1.7.0",
   "description": "",
   "main": "./dist/index.js",
   "type": "module",
@@ -118,6 +118,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 +156,5 @@
       "module": "es2020"
     }
   },
-  "gitHead": "0d323f9884ae8fa48049e25bcd127954ee7988b8"
+  "gitHead": "441c4188533375574d0bd461b3e043ba0c7d2655"
 }

package/src/cli.ts

@@ -15,15 +15,15 @@ import { omitKeys } from './lib/object.js';
 
 import { getConfig, getEnvironmentConfig } from './lib/config.js';
 import { run } from './index.js';
-import { ContentfulConfig } from './types.js';
+import { Config, ContentfulConfig } from './types.js';
 
 const env = dotenv.config();
 dotenvExpand(env);
 
-const parseArgs = (cmd) => ({
-  environment: cmd.env as string,
-  preview: Boolean(cmd.preview),
-  verbose: Boolean(cmd.verbose),
+const parseFetchArgs = (cmd): Partial<Config> => ({
+  preview: cmd.preview as boolean,
+  verbose: cmd.verbose as boolean,
+  ignoreErrors: cmd.ignoreErrors as boolean,
 });
 
 type CommandError = Error & {
@@ -54,7 +54,7 @@ program
   .action(
     actionRunner(async (cmd) => {
       const useTypescript = Boolean(cmd?.typescript ?? false);
-      const config = await getConfig(parseArgs(cmd || {}));
+      const config = await getConfig();
       const verified = await askAll(config);
 
       const environmentConfig = getEnvironmentConfig();
@@ -148,9 +148,10 @@ program
   .description('Fetch content objects')
   .option('-p, --preview', 'Fetch with preview mode')
   .option('-v, --verbose', 'Verbose output')
+  .option('--ignore-errors', 'No error return code when transform has errors')
   .action(
     actionRunner(async (cmd) => {
-      const config = await getConfig(parseArgs(cmd || {}));
+      const config = await getConfig(parseFetchArgs(cmd || {}));
       const verified = await askMissing(config);
 
       return run(verified);

package/src/index.test.ts

@@ -86,4 +86,62 @@ describe('Run', () => {
     expect(output).toMatch(`${chalk.cyan(0)} entries skipped due to validation issues`);
     expect(output).toMatch(`${chalk.red(0)} errors`);
   });
+
+  test('fails on exception before/after', async () => {
+    console.log = jest.fn();
+    const mockError = jest.fn().mockImplementation(() => {
+      throw new Error();
+    });
+
+    await expect(async () => {
+      await run({
+        directory: 'test',
+        before: mockError,
+      });
+    }).rejects.toThrowError();
+
+    await expect(async () => {
+      await run({
+        directory: 'test',
+        after: mockError,
+      });
+    }).rejects.toThrowError();
+  });
+
+  test('fails on transform exception', async () => {
+    console.log = jest.fn();
+    const mockExit = jest.spyOn(process, 'exit').mockImplementation((number) => {
+      throw new Error('process.exit: ' + number);
+    });
+
+    await expect(async () => {
+      await run({
+        directory: 'test',
+        transform: async () => {
+          throw new Error();
+        },
+      });
+    }).rejects.toThrowError();
+
+    expect(mockExit).toHaveBeenCalledWith(1);
+    mockExit.mockRestore();
+  });
+
+  test('does not fail on transform exception with ignoreErrors option', async () => {
+    console.log = jest.fn();
+    const mockExit = jest.spyOn(process, 'exit').mockImplementation((number) => {
+      throw new Error('process.exit: ' + number);
+    });
+
+    await run({
+      directory: 'test',
+      ignoreErrors: true,
+      transform: async () => {
+        throw new Error();
+      },
+    });
+
+    expect(mockExit).toBeCalledTimes(0);
+    mockExit.mockRestore();
+  });
 });

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 { BehaviorSubject } 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';
 
 /**
@@ -73,10 +81,7 @@ export const run = async (config: Config): Promise<void> => {
       {
         title: 'Before Hook',
         skip: (ctx) => !ctx.hooks.has('before'),
-        task: async (ctx) => {
-          const result = await ctx.hooks.before();
-          ctx = { ...ctx, ...(result || {}) };
-        },
+        task: async (ctx) => ctx.hooks.before(),
       },
       {
         title: 'Writing files',
@@ -86,6 +91,8 @@ export const run = async (config: Config): Promise<void> => {
           const tasks = locales.map((locale) => ({
             title: `${locale.code}`,
             task: async () => {
+              const subject = new BehaviorSubject<ObservableContext>(null);
+              const observable = subject.asObservable();
               const data = ctx.localized.get(locale.code);
               const { entries = [] } = data || {};
 
@@ -97,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 = {
@@ -106,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;
@@ -118,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);
                   }
                 }
@@ -135,12 +152,8 @@ export const run = async (config: Config): Promise<void> => {
       {
         title: 'After Hook',
         skip: (ctx) => !ctx.hooks.has('after'),
-        task: async (ctx) => {
-          const result = await ctx.hooks.after();
-          ctx = { ...ctx, ...(result || {}) };
-        },
+        task: async (ctx) => ctx.hooks.after(),
       },
-
       {
         title: 'Cleanup',
         task: async (ctx) => ctx.fileManager.cleanup(),
@@ -152,4 +165,8 @@ export const run = async (config: Config): Promise<void> => {
   const ctx = await tasks.run();
   await ctx.stats.print();
   console.log('\n---------------------------------------------');
+
+  if (ctx.stats.errors?.length && !config.ignoreErrors) {
+    process.exit(1);
+  }
 };

package/src/lib/config.ts

@@ -122,7 +122,7 @@ export const getEnvironmentConfig = (strict = true): ContentfulConfig =>
  * Get configuration
  * @param {Object} args
  */
-export const getConfig = async (args?: Partial<Config>): Promise<Config> => {
+export const getConfig = async (args: Partial<Config> = {}): Promise<Config> => {
   const defaultOptions: Config = {
     environmentId: 'master',
     host: 'api.contentful.com',

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 { BehaviorSubject } 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,110 @@ describe('Utils', () => {
     expect(a).toEqual(['a', 'b', 'c', 'd', 'e']);
     expect(b).toEqual(['e', 'd', 'c', 'b', 'a']);
   });
+
+  test('waitFor', async () => {
+    const subject = new BehaviorSubject<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 BehaviorSubject<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 BehaviorSubject<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');
+  });
 });

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 {
@@ -85,6 +86,7 @@ export type Config = Partial<ContentfulConfig> &
     directory: string;
     managedDirectories?: string[];
     verbose?: boolean;
+    ignoreErrors?: boolean;
     plugins?: Array<[string, KeyValueMap] | PluginInfo | string>;
     resolvedPlugins?: Hooks[];
     preset?: string;
@@ -201,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 & {
@@ -216,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[];