@hahnpro/flow-sdk 9.6.4 → 2025.2.0-beta.1

package/src/lib/utils.ts

@@ -0,0 +1,176 @@
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import { inspect } from 'util';
+
+import { isAxiosError } from 'axios';
+import isPlainObject from 'lodash/isPlainObject';
+import { PythonShell } from 'python-shell';
+import interp from 'string-interp';
+
+import { FlowLogger } from './FlowLogger';
+
+export function fillTemplate(value: any, ...templateVariables: any): any {
+  if (isPlainObject(value)) {
+    for (const key of Object.keys(value)) {
+      value[key] = fillTemplate(value[key], ...templateVariables);
+    }
+    return value;
+  } else if (Array.isArray(value) && value.length > 0) {
+    value.forEach(function (v, index) {
+      this[index] = fillTemplate(v, ...templateVariables);
+    }, value);
+    return value;
+  } else if (value != null && typeof value === 'string' && value.includes('${')) {
+    for (const variables of templateVariables) {
+      try {
+        const result = interp(value, variables || {});
+        if (result) {
+          return result;
+        }
+      } catch (err) {
+        // ignore
+      }
+    }
+  } else {
+    return value;
+  }
+}
+
+export function getCircularReplacer() {
+  const seen = new WeakSet();
+  return (key, value) => {
+    if (typeof value === 'object' && value !== null) {
+      if (seen.has(value)) {
+        return;
+      }
+      seen.add(value);
+    }
+    return value;
+  };
+}
+
+export function toArray(value: string | string[] = []): string[] {
+  return Array.isArray(value) ? value : value.split(',').map((v) => v.trim());
+}
+
+export function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Creates a promise that resolves after a specified delay, with support for cancellation via an AbortSignal.
+ *
+ * @param {number} ms - The delay duration in milliseconds.
+ * @param {Object} [options] - Optional configuration.
+ * @param {AbortSignal} [options.signal] - An AbortSignal to allow cancellation of the delay.
+ *
+ * @returns {Promise<void>} A promise that resolves after the specified delay or rejects if aborted.
+ *
+ * @throws {Error} If the AbortSignal is already aborted or gets aborted during the delay, the promise rejects with an "AbortError".
+ *
+ * @details Usage:
+ * ```typescript
+ * @FlowFunction('test.task.LongRunningTask')
+ * class LongRunningTask extends FlowTask<Properties> {
+ *   private readonly abortController = new AbortController();
+ *
+ *   constructor(...) {...}
+ *
+ *   @InputStream()
+ *   public async loveMeLongTime(event) {
+ *     try {
+ *       await delayWithAbort(this.properties.delay, { signal: this.abortController.signal });
+ *       return this.emitEvent({ foo: 'bar' }, null);
+ *     } catch (err) {
+ *       if (err.message === 'AbortError') {
+ *         return; // Task was aborted
+ *       }
+ *       throw err;
+ *     }
+ *   }
+ *
+ *   public onDestroy = () => { this.abortController.abort(); };
+ * }
+ * ```
+ */
+export function delayWithAbort(ms: number, options?: { signal?: AbortSignal }): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    if (options?.signal?.aborted) {
+      reject(new Error('AbortError'));
+      return;
+    }
+
+    const timeout = setTimeout(() => resolve(), ms);
+
+    options?.signal?.addEventListener('abort', () => {
+      clearTimeout(timeout);
+      reject(new Error('AbortError'));
+    });
+  });
+}
+
+export async function deleteFiles(dir: string, ...filenames: string[]) {
+  for (const filename of filenames) {
+    await fs.unlink(join(dir, filename)).catch((err) => {
+      /*ignore*/
+    });
+  }
+}
+
+export function handleApiError(error: any, logger: FlowLogger) {
+  if (isAxiosError(error)) {
+    const status = error.response?.status ?? error.code ?? '';
+    const statusText = error.response?.statusText ?? '';
+    const url = error.config?.url ?? '[Unknown URL]';
+    const method = error.config?.method?.toUpperCase() ?? '';
+    let errorText = error.response?.data ?? '';
+
+    if (typeof errorText !== 'string') {
+      try {
+        errorText = JSON.stringify(errorText, null, 2);
+      } catch (_) {
+        errorText = '[Unserializable error body]';
+      }
+    }
+    logger.error(`${status} ${statusText}: ${method} request to ${url} failed\n${errorText}`);
+
+    if (error.stack) {
+      logger.error(error.stack);
+    }
+  } else {
+    logger.error(error);
+  }
+}
+
+export function runPyScript(scriptPath: string, data: any) {
+  return new Promise<any>((resolve, reject) => {
+    let pyData: any;
+
+    const pyshell = new PythonShell(scriptPath, { mode: 'text', pythonOptions: ['-u'] });
+    pyshell.send(JSON.stringify(data));
+    pyshell.on('message', (message) => {
+      try {
+        pyData = JSON.parse(message);
+      } catch (err) {
+        pyData = message;
+      }
+    });
+    pyshell.end((err, code, signal) => {
+      if (err) {
+        return reject(err);
+      }
+      return resolve(pyData);
+    });
+  });
+}
+
+/**
+ * Truncates an object or string to the specified max length and depth
+ */
+export function truncate(msg: any, depth = 4, maxStringLength = 1000): string {
+  let truncated = inspect(msg, { depth, maxStringLength });
+  if (truncated.startsWith("'") && truncated.endsWith("'")) {
+    truncated = truncated.substring(1, truncated.length - 1);
+  }
+  return truncated;
+}

package/test/context-manager-purpose.spec.ts

@@ -0,0 +1,248 @@
+import { Type } from 'class-transformer';
+import { IsArray, IsBoolean, IsIn, IsNotEmpty, IsOptional, IsString, ValidateNested } from 'class-validator';
+import { CloudEvent } from 'cloudevents';
+
+import { FlowApplication, FlowEvent, FlowFunction, FlowModule, FlowResource, FlowTask, InputStream } from '../src';
+import { loggerMock } from './mocks/logger.mock';
+
+class Properties {}
+
+@FlowFunction('test.default.trigger')
+class TestTrigger extends FlowResource {
+  constructor(context, properties: unknown) {
+    super(context, properties, Properties);
+  }
+
+  @InputStream()
+  public async onDefault(event) {
+    return this.emitEvent({ empty: 'empty' }, event);
+  }
+}
+
+type ValueDataType = 'string' | 'number' | 'boolean';
+
+@FlowFunction('test.default.Inject')
+export class TestInject extends FlowTask<InjectionProperties> {
+  constructor(context, properties: unknown) {
+    super(context, properties, InjectionProperties, true);
+  }
+
+  @InputStream()
+  public async inject(event: FlowEvent) {
+    const injectedData = event.getData();
+    for (const injection of this.properties.injections || []) {
+      injectedData[injection.key] = this.resolveValue(injection.value, injection.valueDatatype);
+    }
+    return this.emitEvent(injectedData, event);
+  }
+
+  private resolveValue(value: string, valueDatatype: ValueDataType) {
+    let resultValue;
+    switch (valueDatatype) {
+      case 'boolean':
+        resultValue = value === 'true';
+        break;
+      case 'number':
+        resultValue = parseFloat(value);
+        break;
+      default:
+        resultValue = value;
+        break;
+    }
+    return resultValue;
+  }
+}
+
+class Injection {
+  @IsString()
+  key: string;
+
+  @IsString()
+  value: string;
+
+  @IsIn(['string', 'number', 'boolean'])
+  @IsNotEmpty()
+  @IsString()
+  valueDatatype?: 'string' | 'number' | 'boolean';
+}
+
+class InjectionProperties {
+  @IsArray()
+  @Type(() => Injection)
+  @ValidateNested({ each: true })
+  injections: Injection[];
+}
+
+@FlowFunction('test.default.Noop')
+export class TestNoop extends FlowTask<TestProperties> {
+  constructor(context, properties: unknown) {
+    super(context, properties, TestProperties, true);
+  }
+
+  @InputStream()
+  public async noop(event: FlowEvent) {
+    const data = event.getData();
+    if (this.properties.logData === true) {
+      this.logger.log(data, { truncate: false });
+    }
+    return this.emitEvent(data, event);
+  }
+}
+
+class TestProperties {
+  @IsBoolean()
+  @IsOptional()
+  logData?: boolean;
+}
+
+@FlowModule({
+  name: 'test-module',
+  declarations: [TestTrigger, TestInject, TestNoop],
+})
+class TestModule {}
+
+describe('CMTP.1: ContextManager purpose test', () => {
+  const flow = {
+    elements: [
+      { id: 'testTrigger', module: 'test-module', functionFqn: 'test.default.trigger', properties: {} },
+      {
+        id: 'testInject',
+        module: 'test-module',
+        functionFqn: 'test.default.Inject',
+        properties: {
+          injections: [
+            {
+              key: 'value',
+              value: '${flow.value}',
+              valueDatatype: 'number',
+            },
+            {
+              key: 'test',
+              value: '${test}',
+              valueDatatype: 'string',
+            },
+          ],
+        },
+      },
+      { id: 'testNoop', module: 'test-module', functionFqn: 'test.default.Noop', properties: { logData: true } },
+    ],
+    connections: [
+      { id: 'testConnection1', source: 'testTrigger', target: 'testInject' },
+      { id: 'testConnection2', source: 'testInject', target: 'testNoop' },
+    ],
+    context: {
+      flowId: 'testFlow',
+      deploymentId: 'testDeployment',
+    },
+    properties: { value: '123' },
+  };
+
+  let flowApp: FlowApplication;
+  beforeEach(() => {
+    flowApp = new FlowApplication([TestModule], flow, { logger: loggerMock, skipApi: true });
+  });
+
+  afterEach(async () => {
+    await flowApp.destroy();
+  });
+
+  test('CMTP.1.1: Should overwrite all placeholder properties starting with flow. at init', async () => {
+    await flowApp.init();
+    expect(Array.isArray(((flowApp as any).elements['testInject'] as any).properties.injections)).toBe(true);
+    expect(((flowApp as any).elements['testInject'] as any).getPropertiesWithPlaceholders().injections[0].value).toBe('${flow.value}');
+    expect(((flowApp as any).elements['testInject'] as any).properties.injections[0].value).toBe('123');
+    expect(((flowApp as any).elements['testInject'] as any).getPropertiesWithPlaceholders().injections[1].value).toBe('${test}');
+    expect(((flowApp as any).elements['testInject'] as any).properties.injections[1].value).toBe('${test}');
+  });
+
+  test('CMTP.1.2: Should overwrite all placeholder properties starting with flow. also at update', (done) => {
+    let iteration = 0;
+    flowApp.subscribe('testNoop.default', {
+      next: (flowEvent: FlowEvent) => {
+        expect(((flowApp as any).elements['testInject'] as any).getPropertiesWithPlaceholders().injections[0].value).toBe('${flow.value}');
+        expect(((flowApp as any).elements['testInject'] as any).getPropertiesWithPlaceholders().injections[1].value).toBe('${test}');
+
+        const data = flowEvent.getData();
+        expect(data.test).toEqual('${test}');
+
+        iteration++;
+        if (iteration === 1) {
+          expect(data.value).toEqual(123);
+        } else if (iteration === 2) {
+          expect(data.value).toEqual(456);
+        } else if (iteration === 3) {
+          expect(data.value).toEqual(1);
+          done();
+        }
+      },
+    });
+
+    // Check the initial values in first iteration
+    flowApp.emit(new FlowEvent({ id: 'testTrigger' }, {}));
+
+    const cloudEvent = new CloudEvent({
+      source: 'flowstudio/deployments',
+      type: 'com.flowstudio.deployment',
+      subject: 'deploymentId.update',
+    });
+
+    flowApp
+      .onMessage({ ...cloudEvent, data: { properties: { value: 456 } } } as any)
+      .then(() => {
+        // Check the updated values in second iteration
+        return flowApp.emit(new FlowEvent({ id: 'testTrigger' }, {}));
+      })
+      .then(() => {
+        return flowApp.onMessage({ ...cloudEvent, data: { properties: { value: 1 } } } as any);
+      })
+      .then(() => {
+        // Check the updated values in fourth iteration
+        return flowApp.emit(new FlowEvent({ id: 'testTrigger' }, {}));
+      });
+  }, 60000);
+
+  test('CMTP.1.3: Should overwrite all placeholder properties starting with flow. also at update even when the element properties update', (done) => {
+    let iteration = 0;
+    flowApp.subscribe('testNoop.default', {
+      next: (flowEvent: FlowEvent) => {
+        const data = flowEvent.getData();
+        iteration++;
+        if (iteration === 1) {
+          expect((flowApp as any).elements['testInject'].getPropertiesWithPlaceholders().injections.length).toBe(2);
+          expect((flowApp as any).elements['testInject'].getPropertiesWithPlaceholders().injections[0].value).toBe('${flow.value}');
+          expect(data.value).toEqual(123);
+        } else if (iteration === 2) {
+          expect((flowApp as any).elements['testInject'].getPropertiesWithPlaceholders().injections.length).toBe(1);
+          expect((flowApp as any).elements['testInject'].getPropertiesWithPlaceholders().injections[0].value).toBe('987');
+          expect(data.value).toEqual(987);
+          done();
+        }
+      },
+    });
+
+    // Check the initial values in first iteration
+    flowApp.emit(new FlowEvent({ id: 'testTrigger' }, {}));
+
+    flowApp
+      .onMessage({
+        source: 'flowstudio/deployments',
+        type: 'com.flowstudio.deployment',
+        subject: 'deploymentId.update',
+        data: {
+          properties: { flow: { value: 456 } },
+          elements: [
+            {
+              id: 'testInject',
+              properties: {
+                injections: [{ key: 'value', value: '987', valueDatatype: 'number' }],
+              },
+            },
+          ],
+        } as any,
+      } as any)
+      .then(() => {
+        // Check the updated values in second iteration
+        return flowApp.emit(new FlowEvent({ id: 'testTrigger' }, {}));
+      });
+  }, 60000);
+});

package/test/context-manager.spec.ts

@@ -0,0 +1,55 @@
+import { ContextManager } from '../src';
+import { loggerMock } from './mocks/logger.mock';
+
+describe('The ContextManage-Test spec', () => {
+  let contextManager: ContextManager;
+
+  beforeEach(() => {
+    contextManager = new ContextManager(loggerMock, {});
+  });
+
+  test('CMT.1: Should be created', () => {
+    expect(contextManager).toBeDefined();
+  });
+
+  describe('CMT.2: The ContextManager set method', () => {
+    test('CMT.2.1: Should set a property', () => {
+      contextManager.set('test', 'value');
+      expect(contextManager.get('test')).toBe('value');
+    });
+
+    test('CMT.2.2: Should not set a property with flow.', () => {
+      contextManager.set('flow.test', 'value');
+      expect(loggerMock.error).toHaveBeenCalled();
+    });
+
+    test('CMT.2.3: Should overwrite a property', () => {
+      contextManager.set('test', 'value');
+      expect(contextManager.get('test')).toBe('value');
+      contextManager.set('test', 'value2');
+      expect(contextManager.get('test')).toBe('value2');
+    });
+  });
+
+  describe('CMT.3: The ContextManager get method', () => {
+    test('CMT.3.1: Should get a property', () => {
+      contextManager.set('test', 'value');
+      expect(contextManager.get('test')).toBe('value');
+    });
+
+    test('CMT.3.2: Should get undefined for not set property', () => {
+      expect(contextManager.get('test')).toBeUndefined();
+    });
+  });
+
+  describe('CMT.4: The ContextManager update method', () => {
+    test('CMT.4.1: Should set the property to the value property', () => {
+      contextManager.overwriteAllProperties({ test: 'bar' });
+      contextManager.set('not-flow', 'foo');
+      contextManager.updateFlowProperties({ test: 'baz' });
+
+      expect(contextManager.get('not-flow')).toBe('foo');
+      expect(contextManager.get('flow.test')).toBe('baz');
+    });
+  });
+});

package/test/context.spec.ts

@@ -0,0 +1,180 @@
+import { IsString } from 'class-validator';
+import { CloudEvent } from 'cloudevents';
+
+import { FlowApplication, FlowEvent, FlowFunction, FlowModule, FlowResource, InputStream } from '../src';
+import { loggerMock } from './mocks/logger.mock';
+
+describe('Flow Application', () => {
+  beforeEach(() => {
+    jest.resetAllMocks();
+    jest.clearAllMocks();
+  });
+
+  test('FLOW.CON.1 Simple Flow Application with Long Running Task', (done) => {
+    const flow = {
+      elements: [
+        { id: 'testTrigger', module: 'test-module', functionFqn: 'test.resource.TestResource', properties: { assetId: '' } },
+        { id: 'testResource', module: 'test-module', functionFqn: 'test.resource.TestResource', properties: { assetId: 'abc' } },
+      ],
+      connections: [{ id: 'testConnection1', source: 'testTrigger', target: 'testResource' }],
+      context: {
+        flowId: 'testFlow',
+        deploymentId: 'testDeployment',
+      },
+      properties: { test: '123abcd' },
+    };
+
+    const flowApp = new FlowApplication([TestModule], flow, { logger: loggerMock, skipApi: true });
+
+    let iteration = 0;
+    flowApp.subscribe('testResource.default', {
+      next: (event1: FlowEvent) => {
+        const data = event1.getData();
+        iteration++;
+        if (iteration === 1) {
+          expect(data.assetId).toEqual('abc');
+          expect(data.event).toEqual({});
+          expect(data.elementProps).toEqual({ assetId: 'abc' });
+          expect(data.flowProps).toEqual({ flow: { test: '123abcd' } });
+        } else if (iteration === 2) {
+          expect(data.assetId).toEqual('xyz');
+          expect(data.event).toEqual({});
+          expect(data.elementProps).toEqual({ assetId: 'xyz' });
+          expect(data.flowProps).toEqual({ flow: { test: '123abcd' } });
+        } else if (iteration === 3) {
+          expect(data.assetId).toEqual('123');
+          expect(data.event).toEqual({});
+          expect(data.elementProps).toEqual({ assetId: '123' });
+          expect(data.flowProps).toEqual({ flow: { test: 42 } });
+          done();
+        }
+      },
+    });
+
+    flowApp.emit(new FlowEvent({ id: 'testTrigger' }, {}));
+
+    flowApp
+      .onMessage(
+        new CloudEvent<any>({
+          source: 'flowstudio/deployments',
+          type: 'com.flowstudio.deployment',
+          data: { elements: [{ id: 'testResource', properties: { assetId: 'xyz' } }] },
+          subject: 'deploymentId.update',
+        }),
+      )
+      .then(() => {
+        return flowApp.emit(new FlowEvent({ id: 'testTrigger' }, {}));
+      })
+      .then(() => {
+        return flowApp.onMessage(
+          new CloudEvent<any>({
+            subject: 'deploymentId.update',
+            source: 'flowstudio/deployments',
+            type: 'com.flowstudio.deployment',
+            data: {
+              elements: [{ id: 'testResource', properties: { assetId: '123' } }],
+              properties: { test: 42 },
+            },
+          }),
+        );
+      })
+      .then(() => {
+        return flowApp.emit(new FlowEvent({ id: 'testTrigger' }, {}));
+      });
+  }, 10000);
+
+  test('FLOW.CON.2 string interpolation with event data', async () => {
+    let tr = new TestResource({ id: 'testResource', logger: loggerMock }, { assetId: '${test}' });
+    let event = await tr.onDefault(new FlowEvent({ id: 'tr' }, { test: 'xyz' }));
+    let data = event.getData();
+    expect(data).toBeDefined();
+    expect(data.assetId).toBe('xyz');
+
+    tr = new TestResource({ id: 'testResource', logger: loggerMock }, { assetId: '${test}' });
+    event = await tr.onDefault(new FlowEvent({ id: 'tr' }, { nottest: 'xyz' }));
+    data = event.getData();
+    expect(data).toBeDefined();
+    expect(data.assetId).toBeUndefined();
+  });
+
+  test('FLOW.CON.3 string interpolation with flow context properties', (done) => {
+    const flow = {
+      elements: [
+        { id: 'testTrigger', module: 'test-module', functionFqn: 'test.resource.TestResource', properties: { assetId: '' } },
+        { id: 'testResource', module: 'test-module', functionFqn: 'test.resource.TestResource', properties: { assetId: '${test}' } },
+      ],
+      connections: [{ id: 'testConnection1', source: 'testTrigger', target: 'testResource' }],
+      context: { flowId: 'testFlow', deploymentId: 'testDeployment' },
+      properties: { test: '123abcd' },
+    };
+    const flowApp = new FlowApplication([TestModule], flow, { logger: loggerMock, skipApi: true });
+
+    let count = 0;
+    flowApp.subscribe('testResource.default', {
+      next: (event: FlowEvent) => {
+        const data = event.getData();
+        expect(data).toBeDefined();
+        if (count === 1) {
+          expect(data.assetId).toBe('987zyx');
+          done();
+        } else {
+          expect(data.assetId).toBe(undefined);
+          count++;
+        }
+      },
+    });
+    flowApp.emit(new FlowEvent({ id: 'testTrigger' }, { x: 'y' }));
+    flowApp.emit(new FlowEvent({ id: 'testTrigger' }, { test: '987zyx' }));
+  });
+
+  test('FLOW.CON.4 untruncated logging', async () => {
+    const tr = new TestResource({ id: 'testResource', logger: loggerMock }, { assetId: '1234' });
+    await tr.onDefault(new FlowEvent({ id: 'tr' }, { test: 'tyz' }));
+    expect(loggerMock.verbose).toHaveBeenCalledTimes(1);
+    expect(loggerMock.verbose).toHaveBeenCalledWith(expect.stringContaining('test'), expect.objectContaining({ truncate: false }));
+  });
+
+  test('Flow.CON.5 creation of element without app', () => {
+    const elem = new TestResource(
+      {
+        id: 'testResource',
+        logger: loggerMock,
+        app: {
+          emit: jest.fn(),
+          emitPartial: jest.fn(),
+        },
+      },
+      { assetId: '1234' },
+    );
+
+    elem.onDefault(new FlowEvent({ id: 'tr' }, { test: 'tyz' }));
+    expect(loggerMock.verbose).toHaveBeenCalledTimes(1);
+  });
+});
+
+@FlowFunction('test.resource.TestResource')
+class TestResource extends FlowResource {
+  constructor(context, properties: unknown) {
+    super(context, properties, Properties);
+  }
+
+  @InputStream()
+  public async onDefault(event) {
+    const assetId = this.interpolate(this.properties.assetId, event.getData(), this.flowProperties);
+    const data = { assetId, event: {}, elementProps: this.properties, flowProps: this.flowProperties };
+
+    this.logger.verbose('test', { truncate: false });
+    return this.emitEvent(data, event);
+  }
+}
+
+class Properties {
+  @IsString()
+  assetId: string;
+}
+
+@FlowModule({
+  name: 'test-module',
+  declarations: [TestResource],
+})
+class TestModule {}