@erxes/api-shared 0.0.0-stage → 3.2.19-1

package/src/core-modules/segments/evaluate.ts

@@ -0,0 +1,388 @@
+import {
+  segmentFieldRef,
+  segmentReferenceRef,
+  segmentRelationRef,
+} from './nodeRefs';
+import {
+  PERIOD_OPERATORS,
+  SegmentOperator,
+  normalizeSegmentOperator,
+} from './operators';
+
+import { SegmentFieldNode, SegmentNode, SegmentValue } from './nodes';
+import {
+  DEFAULT_SEGMENT_TIME_ZONE,
+  isAnniversary,
+  shiftZonedDays,
+  zonedDate,
+  zonedPeriodRange,
+} from './zonedTime';
+
+export type SegmentEvaluationState = 'matched' | 'notMatched' | 'unknown';
+
+export type SegmentDecideContext = {
+  subjectType?: string;
+  values: ReadonlyMap<string, unknown>;
+  unavailable?: ReadonlySet<string>;
+  now?: Date;
+  timeZone?: string;
+};
+
+const MINUTE_MS = 60_000;
+
+const toList = (value: unknown): unknown[] =>
+  Array.isArray(value) ? value : [value];
+
+const isPresent = (value: unknown): boolean => {
+  if (value === undefined || value === null) {
+    return false;
+  }
+
+  return !(Array.isArray(value) && value.length === 0);
+};
+
+const toOrdinal = (value: unknown): number | undefined => {
+  if (value instanceof Date) {
+    return value.getTime();
+  }
+
+  if (typeof value === 'number') {
+    return Number.isNaN(value) ? undefined : value;
+  }
+
+  if (typeof value === 'string' && value.trim() !== '') {
+    const numeric = Number(value.replace(/,/g, ''));
+
+    if (!Number.isNaN(numeric)) {
+      return numeric;
+    }
+
+    const parsed = Date.parse(value);
+
+    return Number.isNaN(parsed) ? undefined : parsed;
+  }
+
+  return undefined;
+};
+
+const sameValue = (value: unknown, expected: SegmentValue): boolean => {
+  const left = toOrdinal(value);
+  const right = toOrdinal(expected);
+
+  if (left !== undefined && right !== undefined) {
+    return left === right;
+  }
+
+  return String(value) === String(expected);
+};
+
+const anyInCommon = (value: unknown, expected: SegmentValue): boolean =>
+  toList(expected).some((candidate) =>
+    toList(value).some((item) => sameValue(item, candidate as SegmentValue)),
+  );
+
+const containsText = (value: unknown, expected: SegmentValue): boolean =>
+  String(value).toLowerCase().includes(String(expected).toLowerCase());
+
+const compareOrdinal = (
+  value: unknown,
+  expected: SegmentValue,
+  direction: 'gte' | 'lte',
+): boolean => {
+  const right = toOrdinal(expected);
+
+  if (right === undefined) {
+    return false;
+  }
+
+  return toList(value).some((item) => {
+    const left = toOrdinal(item);
+
+    if (left === undefined) {
+      return false;
+    }
+
+    return direction === 'gte' ? left >= right : left <= right;
+  });
+};
+
+const matchesMinuteBucket = (
+  value: unknown,
+  expected: SegmentValue,
+  now: Date,
+  offset: 1 | -1,
+): boolean => {
+  const amount = toOrdinal(expected);
+
+  if (amount === undefined) {
+    return false;
+  }
+
+  const target = Math.floor(
+    (now.getTime() + offset * amount * MINUTE_MS) / MINUTE_MS,
+  );
+
+  return toList(value).some((item) => {
+    const left = toOrdinal(item);
+
+    return left !== undefined && Math.floor(left / MINUTE_MS) === target;
+  });
+};
+
+const matchesDayBucket = (
+  value: unknown,
+  expected: SegmentValue,
+  now: Date,
+  timeZone: string,
+  offset: 1 | -1,
+): boolean => {
+  const amount = toOrdinal(expected);
+
+  if (amount === undefined) {
+    return false;
+  }
+
+  const target = shiftZonedDays(zonedDate(now, timeZone), offset * amount);
+
+  return toList(value).some((item) => {
+    const at = toOrdinal(item);
+
+    if (at === undefined) {
+      return false;
+    }
+
+    const on = zonedDate(new Date(at), timeZone);
+
+    return (
+      on.year === target.year &&
+      on.month === target.month &&
+      on.day === target.day
+    );
+  });
+};
+
+const matchesAnniversary = (
+  value: unknown,
+  expected: SegmentValue | undefined,
+  now: Date,
+  timeZone: string,
+  offset: 0 | 1 | -1,
+): boolean => {
+  const amount = offset === 0 ? 0 : toOrdinal(expected);
+
+  if (amount === undefined) {
+    return false;
+  }
+
+  const target = shiftZonedDays(zonedDate(now, timeZone), offset * amount);
+
+  return toList(value).some((item) => {
+    const at = toOrdinal(item);
+
+    return at !== undefined && isAnniversary(new Date(at), target, timeZone);
+  });
+};
+
+const matchesOperator = (
+  operator: SegmentOperator,
+  value: unknown,
+  expected: SegmentValue | undefined,
+  now: Date,
+  timeZone: string,
+): boolean => {
+  switch (operator) {
+    case SegmentOperator.IsSet:
+      return isPresent(value);
+    case SegmentOperator.IsNotSet:
+      return !isPresent(value);
+    case SegmentOperator.IsTrue:
+      return toList(value).some((item) => item === true || item === 'true');
+    case SegmentOperator.IsFalse:
+      return toList(value).some((item) => item === false || item === 'false');
+    case SegmentOperator.AnniversaryToday:
+      return matchesAnniversary(value, expected, now, timeZone, 0);
+    default:
+      break;
+  }
+
+  const period = PERIOD_OPERATORS[operator];
+
+  if (period) {
+    const { gte, lt } = zonedPeriodRange(now, timeZone, period);
+
+    return toList(value).some((item) => {
+      const at = toOrdinal(item);
+
+      return at !== undefined && at >= gte.getTime() && at < lt.getTime();
+    });
+  }
+
+  if (expected === undefined) {
+    return false;
+  }
+
+  switch (operator) {
+    case SegmentOperator.Equals:
+      return toList(value).some((item) => sameValue(item, expected));
+    case SegmentOperator.NotEquals:
+      return !toList(value).some((item) => sameValue(item, expected));
+    case SegmentOperator.Contains:
+      return (
+        isPresent(value) && toList(value).some((i) => containsText(i, expected))
+      );
+    case SegmentOperator.NotContains:
+      return !toList(value).some((item) => containsText(item, expected));
+
+    case SegmentOperator.In:
+      return anyInCommon(value, expected);
+    case SegmentOperator.NotIn:
+      return !anyInCommon(value, expected);
+
+    case SegmentOperator.NumberGt:
+    case SegmentOperator.DateGte:
+      return compareOrdinal(value, expected, 'gte');
+    case SegmentOperator.NumberLt:
+    case SegmentOperator.DateLte:
+      return compareOrdinal(value, expected, 'lte');
+
+    case SegmentOperator.MinutesFromNow:
+      return matchesMinuteBucket(value, expected, now, 1);
+    case SegmentOperator.MinutesAgo:
+      return matchesMinuteBucket(value, expected, now, -1);
+    case SegmentOperator.DaysFromNow:
+      return matchesDayBucket(value, expected, now, timeZone, 1);
+    case SegmentOperator.DaysAgo:
+      return matchesDayBucket(value, expected, now, timeZone, -1);
+
+    case SegmentOperator.AnniversaryFromNow:
+      return matchesAnniversary(value, expected, now, timeZone, 1);
+    case SegmentOperator.AnniversaryAgo:
+      return matchesAnniversary(value, expected, now, timeZone, -1);
+
+    default:
+      return false;
+  }
+};
+
+const decideField = (
+  node: SegmentFieldNode,
+  context: SegmentDecideContext,
+  now: Date,
+  timeZone: string,
+): SegmentEvaluationState => {
+  const ref = segmentFieldRef(node);
+
+  if (context.unavailable?.has(ref)) {
+    return 'unknown';
+  }
+
+  const operator = normalizeSegmentOperator(node.operator);
+
+  return matchesOperator(
+    operator,
+    context.values.get(ref),
+    node.value,
+    now,
+    timeZone,
+  )
+    ? 'matched'
+    : 'notMatched';
+};
+
+const combine = (
+  conjunction: 'and' | 'or',
+  states: SegmentEvaluationState[],
+): SegmentEvaluationState => {
+  if (conjunction === 'and') {
+    if (states.includes('notMatched')) {
+      return 'notMatched';
+    }
+
+    return states.every((state) => state === 'matched') ? 'matched' : 'unknown';
+  }
+
+  if (states.includes('matched')) {
+    return 'matched';
+  }
+
+  return states.every((state) => state === 'notMatched')
+    ? 'notMatched'
+    : 'unknown';
+};
+
+export const decideSegmentNode = (
+  node: SegmentNode,
+  context: SegmentDecideContext,
+): SegmentEvaluationState => {
+  const now = context.now || new Date();
+  const timeZone = context.timeZone || DEFAULT_SEGMENT_TIME_ZONE;
+
+  if (node.kind === 'field') {
+    return decideField(node, context, now, timeZone);
+  }
+
+  if (node.kind === 'segment') {
+    if (!context.subjectType) {
+      return 'unknown';
+    }
+
+    const ref = segmentReferenceRef(context.subjectType);
+
+    if (context.unavailable?.has(ref)) {
+      return 'unknown';
+    }
+
+    const member = toList(context.values.get(ref)).some(
+      (id) => id === node.segmentId,
+    );
+
+    return (node.exclude ? !member : member) ? 'matched' : 'notMatched';
+  }
+
+  if (node.kind === 'relation') {
+    const ref = segmentRelationRef(node);
+
+    if (context.unavailable?.has(ref)) {
+      return 'unknown';
+    }
+
+    const resolved = context.values.get(ref);
+
+    if (resolved === undefined) {
+      return 'unknown';
+    }
+
+    if (node.measure.op === 'exists' || node.measure.op === 'none') {
+      if (typeof resolved !== 'boolean') {
+        return 'unknown';
+      }
+
+      const present = node.measure.op === 'exists' ? resolved : !resolved;
+
+      return present ? 'matched' : 'notMatched';
+    }
+
+    if (!node.operator) {
+      return 'unknown';
+    }
+
+    return matchesOperator(
+      normalizeSegmentOperator(node.operator),
+      resolved,
+      node.value,
+      now,
+      timeZone,
+    )
+      ? 'matched'
+      : 'notMatched';
+  }
+
+  if (!node.children.length) {
+    return 'unknown';
+  }
+
+  return combine(
+    node.conjunction,
+    node.children.map((child) => decideSegmentNode(child, context)),
+  );
+};

package/src/core-modules/segments/evaluateBatch.test.ts

@@ -0,0 +1,233 @@
+import { segmentRelationRef } from './nodeRefs';
+import { SegmentOperator } from './operators';
+import { SegmentRelationMeta } from './relationRegistry';
+import {
+  evaluateSegmentBatch,
+  measureSegmentSubject,
+  SegmentEvaluationGateway,
+  segmentNodeAt,
+} from './evaluateBatch';
+
+import { SegmentNode, SegmentRelationNode } from './nodes';
+import { SegmentValueRequest } from './plan';
+
+const dealsRelation: SegmentRelationMeta = {
+  key: 'customer.deals',
+  label: 'Deals',
+  subjectType: 'core:contacts.customers',
+  relatedType: 'sales:sales.deals',
+  join: {
+    via: 'relation',
+    subjectRecordType: 'core:contacts.customers',
+    relatedRecordType: 'sales:deal',
+  },
+};
+
+const relationDirectory = {
+  owners: new Map([['customer.deals', 'sales']]),
+  relations: new Map([['customer.deals', dealsRelation]]),
+};
+
+const tagCondition: SegmentNode = {
+  kind: 'field',
+  contentType: 'core:contacts.customers',
+  fieldKey: 'tagIds',
+  operator: SegmentOperator.Equals,
+  value: 'tag-1',
+};
+
+const dealCount: SegmentRelationNode = {
+  kind: 'relation',
+  relationKey: 'customer.deals',
+  measure: { op: 'count' },
+  operator: SegmentOperator.Equals,
+  value: 1,
+};
+
+const segment = {
+  _id: 'segment-1',
+  contentType: 'core:contacts.customers',
+  root: {
+    kind: 'group',
+    conjunction: 'and',
+    children: [tagCondition, dealCount],
+  } as SegmentNode,
+};
+
+const countRef = segmentRelationRef(dealCount);
+
+const gatewayWith = (
+  stub: Partial<SegmentEvaluationGateway>,
+): SegmentEvaluationGateway => ({
+  relationsFor: async () => relationDirectory,
+  resolveFields: async () => ({ values: {} }),
+  resolveEdges: async () => ({}),
+  ...stub,
+});
+
+describe('evaluateSegmentBatch', () => {
+  it('splits subjects into matched, notMatched and undecided', async () => {
+    const gateway = gatewayWith({
+      resolveEdges: async () => ({ 'c-1': ['d-1'], 'c-2': ['d-1', 'd-2'] }),
+      resolveFields: async (plugin) =>
+        plugin === 'core'
+          ? {
+              values: {
+                'c-1': { 'core:contacts.customers.tagIds': ['tag-1'] },
+                'c-2': { 'core:contacts.customers.tagIds': ['tag-1'] },
+                'c-3': { 'core:contacts.customers.tagIds': ['tag-9'] },
+              },
+            }
+          : {
+              values: {
+                'c-1': { [countRef]: 1 },
+                'c-2': { [countRef]: 2 },
+                'c-3': { [countRef]: 0 },
+              },
+            },
+    });
+
+    const result = await evaluateSegmentBatch(gateway, segment, [
+      'c-1',
+      'c-2',
+      'c-3',
+    ]);
+
+    expect(result.matched).toEqual(['c-1']);
+    expect(result.notMatched).toEqual(['c-2', 'c-3']);
+    expect(result.undecided).toEqual([]);
+  });
+
+  it('leaves a subject undecided when a plugin fails', async () => {
+    const gateway = gatewayWith({
+      resolveEdges: async () => ({ 'c-1': ['d-1'] }),
+      resolveFields: async (plugin) => {
+        if (plugin === 'sales') {
+          throw new Error('sales is down');
+        }
+
+        return {
+          values: { 'c-1': { 'core:contacts.customers.tagIds': ['tag-1'] } },
+        };
+      },
+    });
+
+    const result = await evaluateSegmentBatch(gateway, segment, ['c-1']);
+
+    expect(result).toEqual({
+      matched: [],
+      notMatched: [],
+      undecided: ['c-1'],
+    });
+  });
+
+  it('hands the measuring plugin the edges it cannot resolve itself', async () => {
+    const seen: SegmentValueRequest[] = [];
+
+    const gateway = gatewayWith({
+      resolveEdges: async () => ({ 'c-1': ['d-1', 'd-2'] }),
+      resolveFields: async (plugin, input) => {
+        if (plugin === 'sales') {
+          seen.push(...input.requests);
+        }
+
+        return { values: {} };
+      },
+    });
+
+    await evaluateSegmentBatch(gateway, segment, ['c-1']);
+
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).toMatchObject({
+      kind: 'relation',
+      relationKey: 'customer.deals',
+      edges: { 'c-1': ['d-1', 'd-2'] },
+    });
+  });
+
+  it('asks for edges once per related type, not once per request', async () => {
+    let edgeLookups = 0;
+
+    const twoMeasures: SegmentNode = {
+      kind: 'group',
+      conjunction: 'and',
+      children: [
+        dealCount,
+        {
+          kind: 'relation',
+          relationKey: 'customer.deals',
+          measure: { op: 'sum', fieldKey: 'totalAmount' },
+          operator: SegmentOperator.NumberGt,
+          value: 100,
+        },
+      ],
+    };
+
+    const gateway = gatewayWith({
+      resolveEdges: async () => {
+        edgeLookups++;
+        return { 'c-1': ['d-1'] };
+      },
+    });
+
+    await evaluateSegmentBatch(gateway, { ...segment, root: twoMeasures }, [
+      'c-1',
+    ]);
+
+    expect(edgeLookups).toBe(1);
+  });
+
+  it('reads nothing for an empty batch', async () => {
+    let touched = false;
+
+    const gateway = gatewayWith({
+      relationsFor: async () => {
+        touched = true;
+        return relationDirectory;
+      },
+    });
+
+    expect(await evaluateSegmentBatch(gateway, segment, [])).toEqual({
+      matched: [],
+      notMatched: [],
+      undecided: [],
+    });
+    expect(touched).toBe(false);
+  });
+});
+
+describe('measureSegmentSubject', () => {
+  it('finds a condition by its place in the tree', () => {
+    expect(segmentNodeAt(segment.root, 'children.1')).toBe(dealCount);
+    expect(segmentNodeAt(segment.root, '')).toBe(segment.root);
+    expect(segmentNodeAt(segment.root, 'children.7')).toBeUndefined();
+  });
+
+  it("reads what a relation condition measures for one subject", async () => {
+    const gateway = gatewayWith({
+      resolveEdges: async () => ({ 'c-1': ['d-1', 'd-2'] }),
+      resolveFields: async (plugin) =>
+        plugin === 'core'
+          ? { values: {} }
+          : { values: { 'c-1': { [countRef]: 2 } } },
+    });
+
+    expect(
+      await measureSegmentSubject(gateway, segment, 'c-1', ['children.1']),
+    ).toEqual({ 'children.1': 2 });
+  });
+
+  it('ignores a path that is not a relation condition', async () => {
+    const resolveFields = jest.fn(async () => ({ values: {} }));
+
+    expect(
+      await measureSegmentSubject(
+        gatewayWith({ resolveFields }),
+        segment,
+        'c-1',
+        ['children.0', 'children.9'],
+      ),
+    ).toEqual({});
+    expect(resolveFields).not.toHaveBeenCalled();
+  });
+});