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

package/src/lib/flow.interface.ts

@@ -0,0 +1,56 @@
+import { Owner } from '@hahnpro/hpc-api';
+
+export interface FlowContext {
+  deploymentId?: string;
+  diagramId?: string;
+  flowId?: string;
+  owner?: Owner;
+}
+
+export interface FlowElementContext extends FlowContext {
+  id: string;
+  name?: string;
+  functionFqn?: string;
+  inputStreamId?: string;
+}
+
+export interface DeploymentMessage extends Record<string, any> {
+  elementId?: string;
+}
+
+interface FlowElement {
+  id: string;
+  name?: string;
+  properties?: Record<string, any>;
+  module: string;
+  functionFqn: string;
+}
+
+interface FlowConnection {
+  id: string;
+  name?: string;
+  source: string;
+  target: string;
+  sourceStream?: string;
+  targetStream?: string;
+}
+
+export interface Flow {
+  elements: FlowElement[];
+  connections: FlowConnection[];
+  modules?: string[];
+  properties?: Record<string, any>;
+  context?: FlowContext;
+}
+
+export interface StreamOptions {
+  concurrent?: number;
+}
+
+export type ClassType<T> = new (...args: any[]) => T;
+
+export enum LifecycleEvent {
+  ACTIVATED = 'com.hahnpro.flow_function.activated',
+  COMPLETED = 'com.hahnpro.flow_function.completed',
+  TERMINATED = 'com.hahnpro.flow_function.terminated',
+}

package/{dist/index.d.ts → src/lib/index.ts}

@@ -1,4 +1,5 @@
 export * from '@hahnpro/hpc-api';
+
 export * from './flow.interface';
 export * from './utils';
 export * from './FlowApplication';
@@ -8,5 +9,7 @@ export * from './FlowLogger';
 export { FlowModule } from './FlowModule';
 export * from './TestModule';
 export * from './unit-decorators';
+
 export * from './ContextManager';
+
 export { IncompatableWith } from './extra-validators';

package/src/lib/nats.ts

@@ -0,0 +1,140 @@
+import {
+  AckPolicy,
+  Consumer,
+  ConsumerConfig,
+  DeliverPolicy,
+  jetstream,
+  JetStreamApiError,
+  jetstreamManager,
+  PubAck,
+  ReplayPolicy,
+} from '@nats-io/jetstream';
+import { ConnectionOptions, NatsConnection } from '@nats-io/nats-core';
+import { connect } from '@nats-io/transport-node';
+import { CloudEvent } from 'cloudevents';
+import { isEqual, omitBy } from 'lodash';
+
+import { Logger } from './FlowLogger';
+
+export type NatsEvent<T> = Pick<CloudEvent<T>, 'type' | 'source' | 'subject' | 'data' | 'datacontenttype' | 'time'>;
+
+export const natsFlowsPrefixFlowDeployment = `fs.flowdeployment`;
+
+// https://docs.nats.io/nats-concepts/jetstream/consumers#configuration
+export const defaultConsumerConfig: ConsumerConfig = {
+  ack_policy: AckPolicy.Explicit,
+  ack_wait: 30_000_000_000, // 30 seconds
+  deliver_policy: DeliverPolicy.All,
+  max_ack_pending: 1000,
+  max_deliver: -1,
+  max_waiting: 512,
+  replay_policy: ReplayPolicy.Instant,
+  num_replicas: 0,
+};
+
+export const FLOWS_STREAM_NAME = 'flows';
+
+export async function getOrCreateConsumer(
+  logger: Logger,
+  natsConnection: NatsConnection,
+  streamName: string,
+  consumerName: string,
+  options: Partial<ConsumerConfig>,
+): Promise<Consumer> {
+  if (!natsConnection || natsConnection.isClosed()) {
+    throw new Error('NATS connection is not available');
+  } else if (!streamName) {
+    throw new Error('Stream name is not available');
+  } else if (!consumerName) {
+    throw new Error('Consumer name is not available');
+  }
+  logger.debug(`Creating consumer ${consumerName} for stream ${streamName}`);
+
+  const jsm = await jetstreamManager(natsConnection);
+  const consumerInfo = await jsm.consumers.info(streamName, consumerName).catch((err: JetStreamApiError) => {
+    if (err.status !== 404) {
+      logger.error(`Could not get consumer info of stream ${streamName}`, err);
+      logger.error(err.message);
+      throw err;
+    }
+  });
+
+  const consumerConfig = { ...defaultConsumerConfig, ...options };
+  if (consumerInfo) {
+    const compared = omitBy(consumerConfig, (value, key) => isEqual(value, consumerInfo.config[key]));
+    if (Object.keys(compared).length !== 0) {
+      await jsm.consumers.update(streamName, consumerName, consumerConfig);
+    }
+  } else {
+    await jsm.consumers.add(streamName, { name: consumerName, ...consumerConfig });
+  }
+  return await jetstream(natsConnection).consumers.get(streamName, consumerName);
+}
+
+export async function natsEventListener(nc: NatsConnection, logger: Logger, reconnectHandler: () => void): Promise<void> {
+  const statusAsyncIterator = nc?.status();
+  if (!statusAsyncIterator) {
+    logger.error('NATS Status-AsyncIterator is not available, cannot listen for events to re-create consumers at reconnects');
+    return;
+  }
+
+  for await (const status of statusAsyncIterator) {
+    // Handle reconnect: event is triggered when the NATS client reconnected to the server
+    if (status.type === 'reconnect') {
+      reconnectHandler();
+    }
+  }
+}
+
+export async function publishNatsEvent<T>(logger: Logger, nc: NatsConnection, event: NatsEvent<T>, subject?: string): Promise<PubAck> {
+  if (!nc || nc.isClosed()) {
+    logger.error('NATS connection is not available, cannot publish event');
+    return null;
+  }
+  const cloudEvent = new CloudEvent<T>({ datacontenttype: 'application/json', ...event });
+  cloudEvent.validate();
+  const js = jetstream(nc);
+  if (js) {
+    return js.publish(subject || `${cloudEvent.type}.${cloudEvent.subject}`, JSON.stringify(cloudEvent.toJSON()), {
+      msgID: cloudEvent.id,
+    });
+  } else {
+    logger.error(`Could not publish nats event, because jetstream is unavailable / undefined`);
+    return null;
+  }
+}
+
+export async function createNatsConnection(config: ConnectionOptions): Promise<NatsConnection> {
+  const servers: string | string[] = config?.servers ?? process.env.NATS_SERVERS?.split(',') ?? [];
+  const reconnect: boolean = config?.reconnect ?? (process.env.NATS_RECONNECT ?? 'true') === 'true';
+
+  // Default maxReconnectAttempts is 10
+  let maxReconnectAttempts: number = config?.maxReconnectAttempts ?? parseInt(process.env.NATS_MAX_RECONNECT_ATTEMPTS ?? '-1', 10);
+  if (isNaN(maxReconnectAttempts)) {
+    maxReconnectAttempts = 10;
+  }
+
+  // Default reconnectTimeWait is 2000ms
+  let reconnectTimeWait: number = config?.reconnectTimeWait ?? parseInt(process.env.NATS_RECONNECT_TIME_WAIT ?? '2000', 10);
+  if (isNaN(reconnectTimeWait)) {
+    reconnectTimeWait = 2000;
+  }
+
+  // Default timeout is 2000ms
+  let timeout: number = config?.timeout ?? parseInt(process.env.NATS_TIMEOUT ?? '2000', 10);
+  if (isNaN(timeout)) {
+    timeout = 2000;
+  }
+
+  const options: ConnectionOptions = {
+    servers,
+    reconnect,
+    maxReconnectAttempts, // <-- maxReconnectAttempts: -1 means infinite reconnect attempts
+    reconnectTimeWait, // <-- reconnectTimeWait: -1 means no wait time between reconnect attempts
+    timeout,
+    user: config?.user ?? process.env.NATS_USER,
+    pass: config.pass ?? process.env.NATS_PASSWORD,
+  };
+
+  return connect(options);
+}

package/src/lib/unit-decorators.ts

@@ -0,0 +1,156 @@
+import { ValidationOptions } from 'class-validator';
+
+import { makeUnitDecorator } from './unit-utils';
+import { units } from './units';
+
+export function IsTime(unit = units.time.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'time', validationOptions);
+}
+
+export function IsLength(unit = units.length.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'length', validationOptions);
+}
+
+export function IsMass(unit = units.mass.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'mass', validationOptions);
+}
+
+export function IsElectricCurrent(unit = units.electricCurrent.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'electricCurrent', validationOptions);
+}
+
+export function IsThermodynamicTemperature(unit = units.thermodynamicTemperature.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'thermodynamicTemperature', validationOptions);
+}
+
+export function IsAmountOfSubstance(unit = units.amountOfSubstance.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'amountOfSubstance', validationOptions);
+}
+
+export function IsLuminousIntensity(unit = units.luminousIntensity.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'luminousIntensity', validationOptions);
+}
+
+export function IsVoltage(unit = units.voltage.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'voltage', validationOptions);
+}
+
+export function IsForce(unit = units.force.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'force', validationOptions);
+}
+
+export function IsEnergy(unit = units.energy.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'energy', validationOptions);
+}
+
+export function IsPower(unit = units.power.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'power', validationOptions);
+}
+
+export function IsPressure(unit = units.pressure.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'pressure', validationOptions);
+}
+
+export function IsFrequency(unit = units.frequency.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'frequency', validationOptions);
+}
+
+export function IsArea(unit = units.area.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'area', validationOptions);
+}
+
+export function IsVolume(unit = units.volume.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'volume', validationOptions);
+}
+
+export function IsAngle(unit = units.angle.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'angle', validationOptions);
+}
+
+export function IsTranslationalAcceleration(unit = units.translationalAcceleration.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'translationalAcceleration', validationOptions);
+}
+
+export function IsTranslationalVelocity(unit = units.translationalVelocity.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'translationalVelocity', validationOptions);
+}
+
+export function IsTranslationalDisplacement(unit = units.translationalDisplacement.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'translationalDisplacement', validationOptions);
+}
+
+export function IsSpringConstant(unit = units.springConstant.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'springConstant', validationOptions);
+}
+
+export function IsRotationalAcceleration(unit = units.rotationalAcceleration.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'rotationalAcceleration', validationOptions);
+}
+
+export function IsRotationalVelocity(unit = units.rotationalVelocity.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'rotationalVelocity', validationOptions);
+}
+
+export function IsRotationalDisplacement(unit = units.rotationalDisplacement.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'rotationalDisplacement', validationOptions);
+}
+
+export function IsTorque(unit = units.torque.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'torque', validationOptions);
+}
+
+export function IsMomentOfInertia(unit = units.momentOfInertia.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'momentOfInertia', validationOptions);
+}
+
+export function IsRotatingUnbalance(unit = units.rotatingUnbalance.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'rotatingUnbalance', validationOptions);
+}
+
+export function IsMechanicalPower(unit = units.mechanicalPower.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'mechanicalPower', validationOptions);
+}
+
+export function IsMechanicalEnergy(unit = units.mechanicalEnergy.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'mechanicalEnergy', validationOptions);
+}
+
+export function IsDynamicViscosity(unit = units.dynamicViscosity.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'dynamicViscosity', validationOptions);
+}
+
+export function IsVolumeFlow(unit = units.volumeFlow.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'volumeFlow', validationOptions);
+}
+
+export function IsMassFlow(unit = units.massFlow.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'massFlow', validationOptions);
+}
+
+export function IsHeatFlux(unit = units.heatFlux.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'heatFlux', validationOptions);
+}
+
+export function IsThermalEnergy(unit = units.thermalEnergy.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'thermalEnergy', validationOptions);
+}
+
+export function IsSpecificHeatCapacity(unit = units.specificHeatCapacity.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'specificHeatCapacity', validationOptions);
+}
+
+export function IsThermalTransmittance(unit = units.thermalTransmittance.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'thermalTransmittance', validationOptions);
+}
+
+export function IsElectricalPower(unit = units.electricalPower.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'electricalPower', validationOptions);
+}
+
+export function IsElectricalEnergy(unit = units.electricalEnergy.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'electricalEnergy', validationOptions);
+}
+
+export function IsElectricalFrequency(unit = units.electricalFrequency.baseUnit, validationOptions?: ValidationOptions) {
+  return makeUnitDecorator(unit, 'electricalFrequency', validationOptions);
+}

package/src/lib/unit-utils.ts

@@ -0,0 +1,163 @@
+import {
+  isNumber,
+  registerDecorator,
+  ValidationArguments,
+  ValidationOptions,
+  ValidatorConstraint,
+  ValidatorConstraintInterface,
+} from 'class-validator';
+
+import { dimensionToUnitMap, units } from './units';
+
+export function makeUnitDecorator(unit: string, metric: string, validationOptions?: ValidationOptions) {
+  const conversionFactor = verifyUnit(unit, metric);
+  if (conversionFactor < 0) {
+    throw new Error(`${unit} is not a valid ${metric}.`);
+  }
+  return (object: any, propertyName: string) => {
+    Reflect.defineMetadata(`conversionFactor:${propertyName}`, conversionFactor, object.constructor);
+    registerDecorator({
+      target: object.constructor,
+      propertyName,
+      options: validationOptions,
+      constraints: [metric, unit],
+      validator: UnitArgsValidator,
+    });
+  };
+}
+
+@ValidatorConstraint({ async: false })
+class UnitArgsValidator implements ValidatorConstraintInterface {
+  validate(value: any, validationArguments?: ValidationArguments): Promise<boolean> | boolean {
+    return isNumber(value);
+  }
+
+  defaultMessage(args: ValidationArguments) {
+    return `${args.property} must be a number conforming to the specified constraints`;
+  }
+}
+
+const prefixes: { prefix: string; convfactor: number }[] = [
+  { prefix: 'Y', convfactor: 1e24 },
+  { prefix: 'Z', convfactor: 1e21 },
+  { prefix: 'E', convfactor: 1e18 },
+  { prefix: 'P', convfactor: 1e15 },
+  { prefix: 'T', convfactor: 1e12 },
+  { prefix: 'G', convfactor: 1e9 },
+  { prefix: 'M', convfactor: 1e6 },
+  { prefix: 'k', convfactor: 1e3 },
+  { prefix: 'h', convfactor: 1e2 },
+  { prefix: 'da', convfactor: 1e1 },
+  { prefix: 'd', convfactor: 1e-1 },
+  { prefix: 'c', convfactor: 1e-2 },
+  { prefix: 'm', convfactor: 1e-3 },
+  { prefix: 'μ', convfactor: 1e-6 },
+  { prefix: 'n', convfactor: 1e-9 },
+  { prefix: 'p', convfactor: 1e-12 },
+  { prefix: 'f', convfactor: 1e-15 },
+  { prefix: 'a', convfactor: 1e-18 },
+  { prefix: 'z', convfactor: 1e-21 },
+  { prefix: 'y', convfactor: 1e-24 },
+];
+
+export function verifyUnit(unit: string, metric: string): number {
+  if (unit === '' || metric === '') return -1;
+  const definition = units[metric];
+
+  for (const dimension of definition.dimensions) {
+    const components = dimension.split('*');
+    const nominator = components.filter((v) => !v.includes('-'));
+    const denominator = components.filter((v) => v.includes('-'));
+
+    const nomIndices = computeIndices(unit.split('/')[0], nominator);
+    const denomIndices = computeIndices(unit.split('/')[1] || '', denominator);
+
+    const nomFactor = verifyIndices(nomIndices, unit.split('/')[0]);
+    const denomFactor = verifyIndices(denomIndices, unit.split('/')[1]);
+
+    if (nomFactor > 0 && denomFactor > 0) {
+      return nomFactor / denomFactor;
+    }
+  }
+  return -1;
+}
+
+function verifyIndices(indices: { index: number; length: number; convfactor: number }[][], unit: string): number {
+  if (indices.length === 0 || !unit) return 1;
+
+  const filtered = indices
+    .map((arr) => arr.filter((v) => v.index !== -1))
+    .reduce(
+      (previousValue, currentValue) => {
+        if (currentValue.length > 1) {
+          // copy existing arrays *length* times
+          for (let j = 0; j < currentValue.length - 1; j++) {
+            previousValue.forEach((value) => previousValue.push([...value]));
+          }
+        }
+        let index = 0;
+        while (index < previousValue.length) {
+          previousValue[index].push(currentValue[index % currentValue.length]);
+          index++;
+        }
+
+        return previousValue;
+      },
+      [[]],
+    );
+
+  outer: for (const filteredElement of filtered) {
+    let index = 0;
+    let convfactor = 1;
+    while (index != unit.length) {
+      const find = filteredElement.find((obj) => obj?.index === index);
+      if (!find) continue outer;
+      index += find.length;
+      convfactor *= find.convfactor;
+    }
+    return convfactor;
+  }
+  return -1;
+}
+
+function computeIndices(unit: string, dimensions: string[]) {
+  return dimensions.map((dimension) => {
+    const options = computeUnitOptions(dimension);
+    const indices = options.map((preUnit) => unit.indexOf(preUnit.prefUnit));
+    return indices.map((ind, index) => ({
+      index: ind,
+      length: options[index].prefUnit.length,
+      convfactor: options[index].convfactor,
+      offset: options[index].offset,
+    }));
+  });
+}
+
+export function computeUnitOptions(dimension: string): { prefUnit: string; convfactor: number; offset: number }[] {
+  const definition = units[dimensionToUnitMap[dimension.substring(0, 1)]];
+  const exponent = dimension.length === 1 ? 1 : Number.parseInt(dimension.substring(dimension.length - 1), 10);
+  const withPrefixes = definition.units
+    .filter((unit) => unit.SIPrefixes)
+    .map((unit) =>
+      prefixes.map((prefix) => ({
+        prefUnit: prefix.prefix.concat(unit.unit),
+        convfactor: Math.pow(prefix.convfactor * unit.conversionFactor, exponent),
+        offset: unit.offset || 0,
+      })),
+    )
+    .reduce((prev, curr) => prev.concat(curr), []);
+  const allUnits = withPrefixes.concat(
+    definition.units.map((unit) => ({
+      prefUnit: unit.unit,
+      convfactor: Math.pow(unit.conversionFactor, exponent),
+      offset: unit.offset || 0,
+    })),
+  );
+  return dimension.length > 1 && !dimension.endsWith('-1')
+    ? allUnits.map((unit) => ({
+        prefUnit: `${unit.prefUnit}^${dimension.substring(dimension.length - 1)}`,
+        convfactor: unit.convfactor,
+        offset: unit.offset,
+      }))
+    : allUnits;
+}