@becollective/utils 1.10.2 → 2.0.0

package/src/{opportunityUser.js → opportunityUser.ts}

@@ -1,4 +1,8 @@
-const { pick } = require('lodash');
+const pick = (obj: any, keysToPick: string[] = []) => {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([key]) => keysToPick.includes(key))
+  );
+}
 
 /**
  *

package/src/{password.js → password.ts}

@@ -36,3 +36,5 @@ export const password = {
     }
   },
 };
+
+export default password;

package/src/rrule/date.ts

@@ -0,0 +1,25 @@
+import { DateTime } from 'luxon';
+import rrule from 'rrule';
+
+import { toRruleObj } from './parsing';
+
+// Given a start (Date object) and a duration in milliseconds, return a new Date object specifying the end time
+export const getEndTime = (start, duration) => new Date(start.getTime() + duration);
+
+// Combine a date and time string in formats: YYYYMMDD, HHss
+export const munge = (date, time) => {
+  const datePart = DateTime.fromISO(date).toFormat('YYYYMMDD');
+  return `${datePart}${time}`;
+};
+
+// Return a date object representing the given date and time string in the timezone specified
+export const transpose = (date, time, timezone) => {
+  return DateTime.fromISO(munge(date, time)).setZone(timezone).toDate();
+};
+
+// Gets the start time (HHmm format) in the timezone specified for an rrule
+export const getStartTime = (rule, timezone) => {
+  // eslint-disable-next-line no-undef
+  const obj: any = typeof rule === 'object' ? rrule : toRruleObj(rule);
+  return DateTime.fromISO(obj.DTSTART).setZone(timezone).toFormat('HHmm');
+};

package/src/rrule/index.ts

@@ -0,0 +1,2 @@
+export * from './parsing';
+export * from './date';

package/src/rrule/parsing.ts

@@ -0,0 +1,136 @@
+import { DateTime } from 'luxon';
+
+const omitBy = (obj, predicate) => {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([key, value]) => !predicate(value, key))
+  );
+}
+
+export const toRruleObj = function toRruleObj(str) {
+  const config = (str || '')
+    .split(';')
+    .map((component) => component.split('=', 2))
+    .reduce((all, [k, v]) => {
+      all[k] = v;
+      return all;
+    }, {});
+
+  return omitBy(config, (value, key) => !key || value === null);
+};
+
+export const toRruleStr = function toRruleStr(obj) {
+  const filter = Object.keys(obj).filter((k) => obj[k] !== null && obj[k] !== undefined)
+  const map = filter.map((key) => `${key}=${obj[key]}`)
+  const join = map.join(';');
+  return Object.keys(obj)
+    .filter((k) => obj[k] !== null && obj[k] !== undefined)
+    .map((key) => `${key}=${obj[key]}`)
+    .join(';');
+};
+
+const TOKEN_TYPES = {
+  SIGN: 'SIGN',
+  DAYS: 'DAYS',
+  TIME_START: 'TIME_START',
+  HOURS: 'HOURS',
+  MINUTES: 'MINUTES',
+  SECONDS: 'SECONDS',
+  WEEKS: 'WEEKS',
+  UNKNOWN: 'UNKNOWN',
+};
+
+type token = {
+  type: string;
+  val: number;
+}
+
+export const parseDuration = (duration) => {
+  // --- lexer
+  // follows https://tools.ietf.org/html/rfc5545#section-3.3.6
+  let windowStart = 0;
+  const tokens: token[] = [];
+  for (let windowEnd = 1; windowEnd <= duration.length; windowEnd++) {
+    const token = duration.slice(windowStart, windowEnd);
+    if (/^[+-]?P$/.test(token)) {
+      const val = token[0] === '-' ? -1 : 1;
+      tokens.push({ type: TOKEN_TYPES.SIGN, val: val });
+      windowStart = windowEnd;
+    }
+    else if (/^[0-9]*W$/.test(token)) {
+      const val = parseInt(token.slice(0, -1), 10);
+      tokens.push({ type: TOKEN_TYPES.WEEKS, val: val });
+      windowStart = windowEnd;
+    }
+    else if (/^[0-9]*D$/.test(token)) {
+      const val = parseInt(token.slice(0, -1), 10);
+      tokens.push({ type: TOKEN_TYPES.DAYS, val: val });
+      windowStart = windowEnd;
+    }
+    else if (token === 'T') {
+      tokens.push({ type: TOKEN_TYPES.TIME_START, val: -1 });
+      windowStart = windowEnd;
+    }
+    else if (/^[0-9]*\.?[0-9]*H$/.test(token)) {
+      const val = parseFloat(token.slice(0, -1));
+      tokens.push({ type: TOKEN_TYPES.HOURS, val: val });
+      windowStart = windowEnd;
+    }
+    else if (/^[0-9]*M$/.test(token)) {
+      const val = parseInt(token.slice(0, -1), 10);
+      tokens.push({ type: TOKEN_TYPES.MINUTES, val: val });
+      windowStart = windowEnd;
+    }
+    else if (/^[0-9]*S$/.test(token)) {
+      const val = parseInt(token.slice(0, -1), 10);
+      tokens.push({ type: TOKEN_TYPES.SECONDS, val: val });
+      windowStart = windowEnd;
+    }
+    else if (windowEnd === duration.length) {
+      tokens.push({ type: TOKEN_TYPES.UNKNOWN, val: token });
+      windowStart = windowEnd;
+    }
+  }
+
+  // --- parser
+  // this parser is very permissive and doesn't care about token order, repetitions, etc.
+  let parsedDurationValue: number = 0;
+  // for token type of hours, because we made it support fractions, apply parseInt
+  // to round it up to integer
+  for (const token of tokens) {
+    if (token.type === TOKEN_TYPES.SIGN) parsedDurationValue = token.val;
+    else if (token.type === TOKEN_TYPES.WEEKS) parsedDurationValue = token.val * 7 * 24 * 60 * 60 * 1000;
+    else if (token.type === TOKEN_TYPES.DAYS) parsedDurationValue = token.val * 24 * 60 * 60 * 1000;
+    else if (token.type === TOKEN_TYPES.HOURS) parsedDurationValue = token.val * 60 * 60 * 1000, 10;
+    else if (token.type === TOKEN_TYPES.MINUTES) parsedDurationValue = token.val * 60 * 1000;
+    else if (token.type === TOKEN_TYPES.SECONDS) parsedDurationValue = token.val * 1000;
+    // TODO check if we use this, MILLISECONDS is no longer supported
+    // else if (token.type === TOKEN_TYPES.MILLISECONDS) parsedDurationValue = token.val;
+  }
+
+  return parsedDurationValue;
+};
+
+export const getDuration = (icalObj) => {
+  const duration = icalObj.DURATION;
+
+  // make it v1 backward compatible
+  const dtend = icalObj.DTEND;
+  const dtstart = icalObj.DTSTART;
+
+  if (duration && dtend) {
+    return 0;
+  }
+
+  if (duration) {
+    return parseDuration(duration);
+  }
+
+  if (dtstart && dtend) {
+    const start = DateTime.fromISO(dtstart);
+    const end = DateTime.fromISO(dtend);
+    const difference = end.diff(start);
+    if (!difference.isValid) return 0;
+    return difference.toMillis();
+  }
+  return 0;
+};

package/src/rrule.ts

@@ -0,0 +1,367 @@
+import { RRule, rrulestr } from 'rrule';
+import { DateTime } from 'luxon';
+import { toRruleObj, toRruleStr, getDuration, getEndTime, getStartTime } from './rrule/index';
+import { transpose } from './rrule/date';
+
+type ToFrom = {
+  from: Date,
+  to: Date,
+}
+
+const isEmpty = (obj) => {
+  if (Array.isArray(obj) || typeof obj === 'string') {
+    return obj.length === 0;
+  }
+  return !obj;
+}
+
+const omit = (obj, keys) => {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([key]) => !keys.includes(key))
+  );
+}
+
+const omitBy = (obj, predicate) => {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([key, value]) => !predicate(value, key))
+  );
+}
+
+const logError = (...args) => {
+  const logger = console.error || console.log;
+  logger(...args);
+};
+
+export { toRruleObj, toRruleStr };
+
+// Customised recurrenceRule parser for BeCollective
+// We store DURATION in our rules, which are not supported by rrule
+// We need to return this data and also remove it from our rrule configuration before parsing it
+export const parse = function parse(str) {
+  const icalObj = toRruleObj(str);
+  const duration = getDuration(icalObj);
+  // TODO delete unused?
+  // const until = icalObj.UNTIL;
+  const dtend = icalObj.DTEND;
+  const nondurationItems = omit(icalObj, ['DURATION', 'DTEND']);
+  const rrule = rrulestr(toRruleStr(omitBy(nondurationItems, isEmpty)));
+  return { duration, durationString: icalObj.DURATION, rrule, dtend };
+};
+
+export const validateRruleConfig = (obj) => {
+  const config = obj || {};
+  const REQUIRED_FIELDS = [
+    { field: 'DTSTART', name: 'Start time' },
+    { field: 'RRULE:FREQ', name: 'Frequency (Month/Weekly)' },
+    { field: 'INTERVAL', name: 'Interval' },
+    { field: 'UNTIL', name: 'Until' },
+    { field: 'Duration', name: 'Duration' },
+  ];
+
+  const errors: string[] = [];
+
+  REQUIRED_FIELDS.forEach((fieldConfig) => {
+    if (!config[fieldConfig.field]) {
+      errors.push(`Please enter a ${fieldConfig.name}`);
+    }
+  });
+
+  if (config.DTSTART && config.UNTIL && DateTime.fromISO(config.DTSTART) > DateTime.fromISO(config.UNTIL)) {
+    errors.push('DTSTART must be earlier than or equal to UNTIL');
+  }
+
+  return errors;
+};
+
+export const validateRruleConfigV2 = (bcRruleInstance) => {
+  const rruleInstance = bcRruleInstance.rrule;
+  const REQUIRED_RRULE_FIELDS = [
+    { field: 'dtstart', name: 'Start time' },
+    { field: 'interval', name: 'Interval' },
+    { field: 'until', name: 'Until' },
+  ];
+
+  const REQUIRED_BC_FIELDS = [{ field: 'duration', name: 'Duration' }];
+
+  const REQUIRED_BC_FREQ = {
+    field: 'freq',
+    name: 'Frequency (Month/Weekly/Yearly)',
+    values: [RRule.YEARLY, RRule.WEEKLY, RRule.MONTHLY],
+  };
+
+  const errors: string[] = [];
+
+  REQUIRED_RRULE_FIELDS.forEach((fieldConfig) => {
+    if (!rruleInstance.options[fieldConfig.field]) {
+      errors.push(`Please enter a ${fieldConfig.name}`);
+    }
+  });
+
+  if (!REQUIRED_BC_FREQ.values.includes(rruleInstance.options[REQUIRED_BC_FREQ.field])) {
+    errors.push(`Please enter a ${REQUIRED_BC_FREQ.name}`);
+  }
+
+  REQUIRED_BC_FIELDS.forEach((fieldConfig) => {
+    if (!bcRruleInstance[fieldConfig.field]) {
+      errors.push(`Please enter a ${fieldConfig.name}`);
+    }
+  });
+
+  if (
+    rruleInstance.options.dtstart &&
+    rruleInstance.options.until &&
+    DateTime.fromISO(rruleInstance.options.dtstart) > DateTime.fromISO(rruleInstance.options.until)
+  ) {
+    errors.push('DTSTART must be earlier than or equal to UNTIL');
+  }
+
+  return errors;
+};
+
+/**
+ * a helper function that put offical rrule and becollective rrule fields together
+ * @param {Object} rruleInstance an RRule instance.
+ * @param {*} duration non rrule standard duration field.
+ */
+export const buildBcRruleString = (rruleInstance, duration = '0H') => {
+  let rruleString = rruleInstance.toString();
+  if (duration) {
+    rruleString = `${rruleString};DURATION=${duration}`;
+  }
+  const bcRrule = parse(rruleString);
+  const errors = validateRruleConfigV2(bcRrule);
+  if (errors.length === 0) {
+    return rruleString;
+  }
+  else {
+    throw new Error(JSON.stringify(errors));
+  }
+};
+
+export const isValidRrule = (obj) => validateRruleConfig(obj).length === 0;
+
+/* === TIMEZONE ISSUES WITH RRULE ===
+
+The rrule library does not store, use or account for timezone. The timezone information is lost and this leads to bugs displaying times and with
+generating recurrences. This happens because rrule determines the start time by interpreting DTSTART in the timezone of the runtime
+environment. This is fine when the runtime and an opportunity share the same timezone. However, inconsistencies occur when they
+differ, and daylight savings is introduced.
+
+INCONSISTENT START & END TIMES
+-------------------------------------------
+We want to specify a start and end time (5pm - 7pm)
+Technically we need to express this start and end time as UTC timestamps (2017-07-03 T07:00 - 2017-07-03 T09:00)
+
+This presents a problem when we interpret rrule strings to display and generate recurrences.
+
+Consider that we want a recurrenceRule to apply for ‘Asia/Taipei (+0800 UTC)’ and start at 1500 hours, we would have the following
+UTC timestamp:
+
+2017-07-03 T07:00
+
+If our runtime is using Australia/Melbourne time, rrule would determine the start time of each recurrence to be at T17:00
+
+In Asia/Taipei time, that is T15:00 which is correct
+
+However, fast forward to October when daylight savings kicks in for Australia/Melbourne, and suddenly T17:00 translates to T14:00
+in Asia/Taipei.
+
+As illustrated above, we need to workaround the rrule library by incorporating timezone information in the way we display and
+generate recurrences.
+
+OFF BY ONE DATES
+———————————
+This bug occurs because the start time is determined using runtime’s timezone. When finding recurrences between a set of dates,
+the correct dates and times are found for the runtime’s local timezone. But when the client uses these dates, the timezone
+conversion could cause the date to change.
+
+Example generated start time: 2017-10-10 T20:30 UTC
+If a Melbourne client interprets this timestamp, it would translate to: 2017-10-11 T:07:30 AEST
+
+So time is correct but date is WRONG
+
+
+--- SUMMARY & TLDR ---;
+The rrule spec causes us to lose timezone information and leads to inconsistent interpretations of DTSTART and UNTIL times. This is
+further complicated by the fact that a rule is parsed and interpreted based on code runtime’s timezone, which means we are
+potentially shuffling and converting things between 3 timezones: UTC -> runtime -> opportunity. Hence we must implement several
+“tricks” so that we ignore the time portion from dates and the date portion from times.
+
+***********************************************************/
+
+// Return correct and consistent human readable values for a recurrenceRule
+// We need to ignore DTSTART date component and use only the time component so start time is updated according to daylight
+// savings
+export const recurrenceToText = (recurrenceRule, timezone, isFlexible = false) => {
+  const TIME_FORMAT = 'h:mm a';
+  try {
+    const { duration, rrule: rule } = parse(recurrenceRule);
+
+    const dtstartToTimezone = DateTime.fromJSDate(rule.origOptions.dtstart as Date).setZone(timezone);
+    const untilToTimezone = DateTime.fromJSDate(rule.origOptions.until as Date).setZone(timezone);
+    const rrule = new RRule({
+      ...rule.origOptions,
+      dtstart:
+        DateTime.utc(
+          dtstartToTimezone.year,
+          dtstartToTimezone.month,
+          dtstartToTimezone.day,
+          dtstartToTimezone.hour,
+          dtstartToTimezone.minute,
+          dtstartToTimezone.second
+        )
+        .toJSDate(),
+      tzid: timezone,
+      until:
+        DateTime.utc(
+          untilToTimezone.year,
+          untilToTimezone.month,
+          untilToTimezone.day,
+          untilToTimezone.hour,
+          untilToTimezone.minute,
+          untilToTimezone.second
+        )
+        .toJSDate(),
+    });
+    if (isFlexible) {
+      const hours = duration / 1000 / 60 / 60;
+      let ruleText = rrule.toText();
+      if (rule.origOptions.count === 1) {
+        // When it is not a repeating rule
+        ruleText = ruleText.replace(/every year until/i, 'in total by');
+        ruleText = ruleText.replace(/ \(~ approximate\)/i, '');
+      }
+      return {
+        text: `${hours} hours ${ruleText}`,
+        timezone,
+      };
+    }
+    // Get today's start time in the recurrenceRule's timezone, then convert that timestamp to our local time
+    const end = dtstartToTimezone.plus(duration);
+    return {
+      text: rrule.toText().charAt(0).toUpperCase() + rrule.toText().slice(1),
+      time: `${dtstartToTimezone.toFormat(TIME_FORMAT)} to ${end.toFormat(TIME_FORMAT)}`,
+      timezone,
+    };
+  }
+  catch (e) {
+    return { text: '', time: '', timezone };
+  }
+};
+
+// Return the text based on the specified timezone
+// This method doesn't convert rrule to it's owner opportunity's timezone
+export const recurrenceToTextInTimezone = (recurrenceRule, timezone) => {
+  const TIME_FORMAT = 'h:mm A';
+
+  const localTimezone = timezone || 'UTC';
+
+  try {
+    const { duration, rrule: rule } = parse(recurrenceRule);
+    const start = DateTime.fromISO(getStartTime(recurrenceRule, localTimezone), 'HHmm').setZone(localTimezone);
+    const end = DateTime.fromISO(getEndTime(start.toJSDate(), duration)).setZone(localTimezone);
+    return {
+      text: rule.toText().charAt(0).toUpperCase() + rule.toText().slice(1),
+      time: `${start.toFormat(TIME_FORMAT)} to ${end.toFormat(TIME_FORMAT)}`,
+      localTimezone,
+    };
+  }
+  catch (e) {
+    return { text: '', time: '', localTimezone };
+  }
+};
+
+export const recurrencesBetween = (fromDate, toDate, recurrenceRule, timezone) => {
+  try {
+    // We need to deal with time and dates separately because timestamps will be converted and lead to errors
+    const time = getStartTime(recurrenceRule, timezone);
+    const { duration, rrule: rule } = parse(recurrenceRule);
+    const recurrences = rule.between(fromDate, toDate);
+
+    return recurrences.map((start) => {
+      // eslint-disable-next-line no-undef
+      const fixed = transpose(start, time, timezone);
+      return {
+        from: fixed,
+        to: getEndTime(fixed, duration),
+      };
+    });
+  }
+  catch (e) {
+    logError('Error while generating recurrences between', fromDate.toString(), 'to', toDate.toString());
+    logError('RRULE:', recurrenceRule, 'TIMEZONE:', timezone);
+    logError('***\n\n', e, '\n\n***');
+    return [];
+  }
+};
+
+/**
+ *
+ * @param {*} rrule
+ * @param {*} timezone
+ * @param {*} from
+ * @param {*} isFlexible
+ * @returns an array of date in true utc (DST offset is considered)
+ */
+export const recurrencesBetweenV2 = (rrule, timezone, from = new Date(), isFlexible = false) => {
+  const { duration, rrule: rule } = parse(rrule);
+
+  const dtstartToTimezone = DateTime.fromJSDate(rule.origOptions.dtstart).setZone(timezone);
+  const untilToTimezone = DateTime.fromJSDate(rule.origOptions.until).setZone(timezone);
+  const rruleToConvert = new RRule({
+    ...rule.origOptions,
+    dtstart:
+      DateTime.utc(
+        dtstartToTimezone.year,
+        dtstartToTimezone.month,
+        dtstartToTimezone.day,
+        dtstartToTimezone.hour,
+        dtstartToTimezone.minute,
+        dtstartToTimezone.second
+      ).toJSDate(),
+    tzid: timezone,
+    until:
+      DateTime.utc(
+        untilToTimezone.year,
+        untilToTimezone.month,
+        untilToTimezone.day,
+        untilToTimezone.hour,
+        untilToTimezone.minute,
+        untilToTimezone.second
+      ).toJSDate(),
+  });
+
+  const occurrences = rruleToConvert
+    .all()
+    .map((date) => DateTime.fromJSDate(date).toUTC().setZone('local', { keepLocalTime: true }));
+
+  if (!occurrences.length) {
+    return [];
+  }
+
+  const output: ToFrom[] = [];
+  if(isFlexible) {
+    let i = 0;
+    occurrences.map(o => {
+      output.push({ from: o.toJSDate(), to: o.toJSDate() });
+      // update "to" field
+      if (i > 0) {
+        output[i - 1].to = o.toUTC().minus({ seconds: 1 }).toJSDate();
+      }
+      if (i === occurrences.length - 1) {
+        output[i].to = DateTime.fromJSDate(rule.options.until as Date).toUTC().minus({ seconds: 1 }).toJSDate();
+      }
+      i++;
+    });
+    return output.filter(((o: ToFrom) => from ? DateTime.fromJSDate(o.to) > DateTime.fromJSDate(from) : DateTime.fromJSDate(o.to) < DateTime.fromJSDate(rule.options.until as Date)));
+  } else {
+    const output: ToFrom[] = [];
+    occurrences.map(o => {
+      output.push({
+        from: o.toJSDate(),
+        to: o.toUTC().plus(duration).toJSDate(),
+      });
+    });
+    return output.filter(((o: ToFrom) => from ? DateTime.fromJSDate(o.to) > DateTime.fromJSDate(from) : DateTime.fromJSDate(o.to) < DateTime.fromJSDate(rule.options.until as Date))) as { from: Date, to: Date }[];
+  }
+};