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

package/src/core-modules/properties/valueUsage.ts

@@ -0,0 +1,153 @@
+import { Collection } from 'mongoose';
+import { z } from 'zod';
+
+export enum TPropertyProducers {
+  VALUE_USAGE = 'valueUsage',
+}
+
+export const PropertyValueUsageInput = z.object({
+  contentType: z.string(),
+  // Resolved by core, e.g. propertiesData.g:<groupId>.<fieldId>.
+  path: z.string(),
+  // Samples stop at the first matches; counts may scan the whole collection,
+  // so they are asked for apart and arrive later.
+  part: z.enum(['samples', 'counts']),
+  optionValues: z.array(z.string()).optional(),
+  // Narrows the answer to records holding this one option.
+  value: z.string().optional(),
+});
+
+export type TPropertyValueUsageInput = z.infer<typeof PropertyValueUsageInput>;
+
+export type TPropertyProducersInput = {
+  [TPropertyProducers.VALUE_USAGE]: TPropertyValueUsageInput;
+};
+
+export interface IPropertyValueSamples {
+  // False when the records could not be checked; callers keep the strict rule.
+  known: boolean;
+  samples: { _id: string; label: string }[];
+}
+
+export interface IPropertyValueCounts {
+  known: boolean;
+  count: number;
+  capped: boolean;
+  // null when the per-option tally gave up; saved options then stay archived.
+  byOption: { value: string; count: number }[] | null;
+}
+
+export type TPropertyValueUsage = IPropertyValueSamples | IPropertyValueCounts;
+
+export type TPropertyValueUsageHandler = (args: {
+  subdomain: string;
+  data: TPropertyValueUsageInput;
+}) => Promise<TPropertyValueUsage>;
+
+export const UNKNOWN_VALUE_SAMPLES: IPropertyValueSamples = {
+  known: false,
+  samples: [],
+};
+
+export const UNKNOWN_VALUE_COUNTS: IPropertyValueCounts = {
+  known: false,
+  count: 0,
+  capped: false,
+  byOption: null,
+};
+
+export const unknownValueUsage = (
+  part: TPropertyValueUsageInput['part'],
+): TPropertyValueUsage =>
+  part === 'samples' ? UNKNOWN_VALUE_SAMPLES : UNKNOWN_VALUE_COUNTS;
+
+const COUNT_CAP = 1_000;
+const SAMPLE_LIMIT = 20;
+// No index backs custom fields, so each query gives up rather than stall.
+const MAX_TIME_MS = 3_000;
+
+const valueFilter = ({ path, value }: TPropertyValueUsageInput) => ({
+  [path]: value || { $exists: true },
+});
+
+export const measurePropertyValueSamples = async (
+  collection: Collection,
+  input: TPropertyValueUsageInput,
+  toLabel: (doc: Record<string, unknown>) => string,
+): Promise<IPropertyValueSamples> => {
+  try {
+    const docs = await collection
+      .find(valueFilter(input), { limit: SAMPLE_LIMIT, maxTimeMS: MAX_TIME_MS })
+      .toArray();
+
+    return {
+      known: true,
+      samples: docs.map((doc) => ({
+        _id: String(doc._id),
+        label: toLabel(doc) || String(doc._id),
+      })),
+    };
+  } catch {
+    return UNKNOWN_VALUE_SAMPLES;
+  }
+};
+
+const countOptions = async (
+  collection: Collection,
+  { path, optionValues = [] }: TPropertyValueUsageInput,
+) => {
+  try {
+    const rows = await collection
+      .aggregate<{ _id: unknown; count: number }>(
+        [
+          { $match: { [path]: { $in: optionValues } } },
+          { $project: { v: `$${path}` } },
+          // Rows and multi-selects both nest arrays; a scalar unwinds as itself.
+          { $unwind: '$v' },
+          { $unwind: '$v' },
+          { $match: { v: { $in: optionValues } } },
+          { $group: { _id: '$v', count: { $sum: 1 } } },
+        ],
+        { maxTimeMS: MAX_TIME_MS },
+      )
+      .toArray();
+
+    return rows.map(({ _id, count }) => ({ value: String(_id), count }));
+  } catch {
+    return null;
+  }
+};
+
+// The total and the per-option tally fail apart, so one slow scan keeps the other.
+export const measurePropertyValueCounts = async (
+  collection: Collection,
+  input: TPropertyValueUsageInput,
+): Promise<IPropertyValueCounts> => {
+  const [count, byOption] = await Promise.all([
+    collection
+      .countDocuments(valueFilter(input), {
+        limit: COUNT_CAP,
+        maxTimeMS: MAX_TIME_MS,
+      })
+      .catch(() => null),
+    input.optionValues?.length && !input.value
+      ? countOptions(collection, input)
+      : [],
+  ]);
+
+  if (count === null) {
+    return { ...UNKNOWN_VALUE_COUNTS, byOption };
+  }
+
+  return { known: true, count, capped: count >= COUNT_CAP, byOption };
+};
+
+// Runs where the records live; core and plugins share it so answers match.
+export const measurePropertyValueUsage = (
+  collection: Collection,
+  input: TPropertyValueUsageInput,
+  toLabel: (doc: Record<string, unknown>) => string,
+): Promise<TPropertyValueUsage> =>
+  input.part === 'samples'
+    ? measurePropertyValueSamples(collection, input, toLabel)
+    : measurePropertyValueCounts(collection, input);

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

@@ -0,0 +1,122 @@
+import { segmentFieldRef } from './nodeRefs';
+import { SegmentOperator } from './operators';
+import { decideSegmentNode } from './evaluate';
+import { SegmentFieldMeta } from './fieldMeta';
+import { compileSegmentMongoFilter } from './mongoFilter';
+import { SegmentNode } from './nodes';
+
+const TYPE = 'core:contacts.customers';
+const UB = 'Asia/Ulaanbaatar';
+
+const NOW = new Date('2026-08-31T15:19:00.000Z');
+
+const fields: SegmentFieldMeta[] = [
+  {
+    key: 'birthDate',
+    label: 'Birth date',
+    kind: 'projected',
+    path: 'birthDate',
+    operators: [],
+    input: 'date',
+  },
+];
+
+const node = (operator: SegmentOperator, value?: number): SegmentNode => ({
+  kind: 'field',
+  contentType: TYPE,
+  fieldKey: 'birthDate',
+  operator,
+  value,
+});
+
+const queryMatches = (tree: SegmentNode, birthDate: Date): boolean => {
+  const { filter, unsupported } = compileSegmentMongoFilter(tree, {
+    fields,
+    now: NOW,
+    timeZone: UB,
+  });
+
+  expect(unsupported).toEqual([]);
+
+  const branches = (filter.$or || [filter]) as Record<string, unknown>[];
+
+  return branches.some((branch) => {
+    const range = branch.birthDate as { $gte: Date; $lt: Date };
+
+    return birthDate >= range.$gte && birthDate < range.$lt;
+  });
+};
+
+const decideMatches = (tree: SegmentNode, birthDate: Date): boolean =>
+  decideSegmentNode(tree, {
+    subjectType: TYPE,
+    values: new Map([
+      [
+        segmentFieldRef({ contentType: TYPE, fieldKey: 'birthDate' }),
+        birthDate,
+      ],
+    ]),
+    now: NOW,
+    timeZone: UB,
+  }) === 'matched';
+
+const bothAgree = (tree: SegmentNode, birthDate: Date): boolean => {
+  const queried = queryMatches(tree, birthDate);
+
+  expect(decideMatches(tree, birthDate)).toBe(queried);
+
+  return queried;
+};
+
+describe('anniversary operators', () => {
+  it('matches a birthday falling on the local day', () => {
+    const tree = node(SegmentOperator.AnniversaryToday);
+
+    expect(bothAgree(tree, new Date('1988-08-30T16:00:00Z'))).toBe(true);
+    expect(bothAgree(tree, new Date('2004-08-30T20:00:00Z'))).toBe(true);
+    expect(bothAgree(tree, new Date('1988-08-31T16:00:00Z'))).toBe(false);
+  });
+
+  it('counts forward to a birthday still to come', () => {
+    const tree = node(SegmentOperator.AnniversaryFromNow, 7);
+
+    expect(bothAgree(tree, new Date('1990-09-06T16:00:00Z'))).toBe(true);
+    expect(bothAgree(tree, new Date('1990-09-05T16:00:00Z'))).toBe(false);
+  });
+
+  it('counts back to a birthday already past', () => {
+    const tree = node(SegmentOperator.AnniversaryAgo, 30);
+
+    expect(bothAgree(tree, new Date('1995-07-31T16:00:00Z'))).toBe(true);
+    expect(bothAgree(tree, new Date('1995-08-01T16:00:00Z'))).toBe(false);
+  });
+
+  it('reads an old date against the offset that was in force then', () => {
+    const tree = node(SegmentOperator.AnniversaryAgo, 30);
+
+    expect(bothAgree(tree, new Date('1975-07-31T17:00:00Z'))).toBe(true);
+    expect(bothAgree(tree, new Date('1975-07-31T16:00:00Z'))).toBe(false);
+  });
+
+  it('is undecidable neither way when the date is unset', () => {
+    const tree = node(SegmentOperator.AnniversaryToday);
+
+    expect(
+      decideSegmentNode(tree, {
+        subjectType: TYPE,
+        values: new Map(),
+        now: NOW,
+        timeZone: UB,
+      }),
+    ).toBe('notMatched');
+  });
+
+  it('needs an amount for the counted forms', () => {
+    expect(
+      decideMatches(
+        node(SegmentOperator.AnniversaryFromNow),
+        new Date('1990-08-30T16:00:00Z'),
+      ),
+    ).toBe(false);
+  });
+});

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

@@ -0,0 +1,173 @@
+import { SegmentOperator } from './operators';
+import { SegmentRelationMeta } from './relationRegistry';
+import { segmentDependencies, segmentDependsOnClock } from './dependencies';
+
+import { SegmentNode } from './nodes';
+
+const relations = new Map<string, SegmentRelationMeta>([
+  [
+    'customer.deals',
+    {
+      key: 'customer.deals',
+      label: 'Deals',
+      subjectType: 'core:contacts.customers',
+      relatedType: 'sales:sales.deals',
+      join: {
+        via: 'relation',
+        subjectRecordType: 'core:customer',
+        relatedRecordType: 'sales:deal',
+      },
+    },
+  ],
+]);
+
+const tagged: SegmentNode = {
+  kind: 'field',
+  contentType: 'core:contacts.customers',
+  fieldKey: 'tagIds',
+  operator: SegmentOperator.Equals,
+  value: 'tag-1',
+};
+
+describe('segmentDependencies', () => {
+  it('always includes the segment’s own content type', () => {
+    expect(
+      segmentDependencies('core:contacts.customers', {
+        kind: 'group',
+        conjunction: 'and',
+        children: [],
+      }),
+    ).toEqual(['core:contacts.customers']);
+  });
+
+  it('files the collection a field reads its value out of', () => {
+    const root: SegmentNode = {
+      kind: 'group',
+      conjunction: 'and',
+      children: [
+        {
+          kind: 'field',
+          contentType: 'sales:sales.deals',
+          fieldKey: 'stageProbability',
+          operator: SegmentOperator.Equals,
+          value: 'Won',
+        },
+      ],
+    };
+
+    const fieldSources = new Map([
+      ['sales:sales.deals:stageProbability', ['sales:sales.stages']],
+    ]);
+
+    expect(
+      segmentDependencies('sales:sales.deals', root, undefined, fieldSources),
+    ).toEqual(['sales:sales.deals', 'sales:sales.stages']);
+
+    expect(segmentDependencies('sales:sales.deals', root)).toEqual([
+      'sales:sales.deals',
+    ]);
+  });
+
+  it('reaches the related type through a relation with no predicate', () => {
+    const root: SegmentNode = {
+      kind: 'group',
+      conjunction: 'and',
+      children: [
+        tagged,
+        {
+          kind: 'relation',
+          relationKey: 'customer.deals',
+          measure: { op: 'count' },
+          operator: SegmentOperator.NumberGt,
+          value: 1,
+        },
+      ],
+    };
+
+    expect(
+      segmentDependencies('core:contacts.customers', root, relations),
+    ).toEqual(['core:contacts.customers', 'sales:sales.deals']);
+  });
+
+  it('reads the fields inside a relation predicate', () => {
+    const root: SegmentNode = {
+      kind: 'group',
+      conjunction: 'and',
+      children: [
+        {
+          kind: 'relation',
+          relationKey: 'customer.deals',
+          measure: { op: 'count' },
+          operator: SegmentOperator.Equals,
+          value: 1,
+          child: {
+            kind: 'field',
+            contentType: 'sales:sales.deals',
+            fieldKey: 'stageProbability',
+            operator: SegmentOperator.Equals,
+            value: 'Won',
+          },
+        },
+      ],
+    };
+
+    expect(segmentDependencies('core:contacts.customers', root)).toEqual([
+      'core:contacts.customers',
+      'sales:sales.deals',
+    ]);
+  });
+
+  it('does not repeat a type named more than once', () => {
+    const root: SegmentNode = {
+      kind: 'group',
+      conjunction: 'or',
+      children: [tagged, tagged],
+    };
+
+    expect(segmentDependencies('core:contacts.customers', root)).toEqual([
+      'core:contacts.customers',
+    ]);
+  });
+});
+
+describe('segmentDependsOnClock', () => {
+  const dated = (operator: SegmentOperator): SegmentNode => ({
+    kind: 'field',
+    contentType: 'core:contacts.customers',
+    fieldKey: 'createdAt',
+    operator,
+    value: '30',
+  });
+
+  it('spots a relative operator', () => {
+    expect(segmentDependsOnClock(dated(SegmentOperator.DaysAgo))).toBe(true);
+    expect(segmentDependsOnClock(dated(SegmentOperator.DaysFromNow))).toBe(
+      true,
+    );
+  });
+
+  it('spots a calendar period, which moves on at the turn of each one', () => {
+    expect(segmentDependsOnClock(dated(SegmentOperator.DateThisMonth))).toBe(
+      true,
+    );
+    expect(segmentDependsOnClock(dated(SegmentOperator.DateThisYear))).toBe(
+      true,
+    );
+  });
+
+  it('leaves a fixed date alone - it means the same thing tomorrow', () => {
+    expect(segmentDependsOnClock(dated(SegmentOperator.DateGte))).toBe(false);
+    expect(segmentDependsOnClock(dated(SegmentOperator.Equals))).toBe(false);
+  });
+
+  it('looks inside a relation predicate, where the same trap lives', () => {
+    expect(
+      segmentDependsOnClock({
+        kind: 'relation',
+        relationKey: 'customer.deals',
+        measure: { op: 'exists' },
+        child: dated(SegmentOperator.DaysAgo),
+      }),
+    ).toBe(true);
+  });
+});

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

@@ -0,0 +1,70 @@
+import { SegmentOperator, normalizeSegmentOperator } from './operators';
+import { SegmentRelationMeta } from './relationRegistry';
+import { walkSegmentNodes } from './walkNodes';
+
+import { SegmentNode } from './nodes';
+
+export const segmentDependencyKey = (segmentId: string): string =>
+  `segment:${segmentId}`;
+
+export const segmentDependencies = (
+  contentType: string,
+  root: SegmentNode,
+  relations?: ReadonlyMap<string, SegmentRelationMeta>,
+  fieldSources?: ReadonlyMap<string, string[]>,
+): string[] => {
+  const types = new Set<string>([contentType]);
+
+  for (const node of walkSegmentNodes(root, { intoRelationChild: true })) {
+    if (node.kind === 'field') {
+      types.add(node.contentType);
+
+      const sources =
+        fieldSources?.get(`${node.contentType}:${node.fieldKey}`) || [];
+
+      sources.forEach((source) => types.add(source));
+    }
+
+    if (node.kind === 'segment') {
+      types.add(segmentDependencyKey(node.segmentId));
+    }
+
+    if (node.kind === 'relation') {
+      const related = relations?.get(node.relationKey)?.relatedType;
+
+      if (related) {
+        types.add(related);
+      }
+    }
+  }
+
+  return [...types].sort();
+};
+
+const CLOCK_OPERATORS = new Set<SegmentOperator>([
+  SegmentOperator.DaysAgo,
+  SegmentOperator.DaysFromNow,
+  SegmentOperator.MinutesAgo,
+  SegmentOperator.MinutesFromNow,
+  SegmentOperator.AnniversaryToday,
+  SegmentOperator.AnniversaryFromNow,
+  SegmentOperator.AnniversaryAgo,
+  SegmentOperator.DateThisMonth,
+  SegmentOperator.DateThisQuarter,
+  SegmentOperator.DateThisYear,
+]);
+
+export const segmentDependsOnClock = (root: SegmentNode): boolean => {
+  for (const node of walkSegmentNodes(root, { intoRelationChild: true })) {
+    const operator =
+      node.kind === 'field' || node.kind === 'relation'
+        ? node.operator
+        : undefined;
+
+    if (operator && CLOCK_OPERATORS.has(normalizeSegmentOperator(operator))) {
+      return true;
+    }
+  }
+
+  return false;
+};