launchdarkly-js-sdk-common 4.0.0 → 4.0.1

package/src/jest.setup.js

@@ -0,0 +1 @@
+// Test environment setup

package/src/loggers.js

@@ -0,0 +1,93 @@
+const logLevels = ['debug', 'info', 'warn', 'error', 'none'];
+
+/**
+ * A simple logger that writes to stderr.
+ */
+function commonBasicLogger(options, formatFn) {
+  if (options && options.destination && typeof options.destination !== 'function') {
+    throw new Error('destination for basicLogger was set to a non-function');
+  }
+
+  function toConsole(methodName) {
+    // The global console variable is not guaranteed to be defined at all times in all browsers:
+    // https://www.beyondjava.net/console-log-surprises-with-internet-explorer-11-and-edge
+    return function(line) {
+      if (console && console[methodName]) {
+        console[methodName].call(console, line);
+      }
+    };
+  }
+  const destinations =
+    options && options.destination
+      ? [options.destination, options.destination, options.destination, options.destination]
+      : [toConsole('log'), toConsole('info'), toConsole('warn'), toConsole('error')];
+  const prependLevelToMessage = !!(options && options.destination); // if we're writing to console.warn, etc. we don't need the prefix
+  const prefix =
+    !options || options.prefix === undefined || options.prefix === null ? '[LaunchDarkly] ' : options.prefix;
+
+  let minLevel = 1; // default is 'info'
+  if (options && options.level) {
+    for (let i = 0; i < logLevels.length; i++) {
+      if (logLevels[i] === options.level) {
+        minLevel = i;
+      }
+    }
+  }
+
+  function write(levelIndex, levelName, args) {
+    if (args.length < 1) {
+      return;
+    }
+    let line;
+    const fullPrefix = prependLevelToMessage ? levelName + ': ' + prefix : prefix;
+    if (args.length === 1 || !formatFn) {
+      line = fullPrefix + args[0];
+    } else {
+      const tempArgs = [...args];
+      tempArgs[0] = fullPrefix + tempArgs[0];
+      line = formatFn(...tempArgs);
+    }
+    try {
+      destinations[levelIndex](line);
+    } catch (err) {
+      console &&
+        console.log &&
+        console.log("[LaunchDarkly] Configured logger's " + levelName + ' method threw an exception: ' + err);
+    }
+  }
+
+  const logger = {};
+  for (let i = 0; i < logLevels.length; i++) {
+    const levelName = logLevels[i];
+    if (levelName !== 'none') {
+      if (i < minLevel) {
+        logger[levelName] = () => {};
+      } else {
+        const levelIndex = i;
+        logger[levelName] = function() {
+          // can't use arrow function with "arguments"
+          write(levelIndex, levelName, arguments);
+        };
+      }
+    }
+  }
+
+  return logger;
+}
+
+function validateLogger(logger) {
+  logLevels.forEach(level => {
+    if (level !== 'none' && (!logger[level] || typeof logger[level] !== 'function')) {
+      throw new Error('Provided logger instance must support logger.' + level + '(...) method');
+      // Note that the SDK normally does not throw exceptions to the application, but that rule
+      // does not apply to LDClient.init() which will throw an exception if the parameters are so
+      // invalid that we cannot proceed with creating the client. An invalid logger meets those
+      // criteria since the SDK calls the logger during nearly all of its operations.
+    }
+  });
+}
+
+module.exports = {
+  commonBasicLogger,
+  validateLogger,
+};

package/src/messages.js

@@ -0,0 +1,217 @@
+const errors = require('./errors');
+
+function errorString(err) {
+  if (err && err.message) {
+    return err.message;
+  }
+  if (typeof err === 'string' || err instanceof String) {
+    return err;
+  }
+  return JSON.stringify(err);
+}
+
+const clientInitialized = function() {
+  return 'LaunchDarkly client initialized';
+};
+
+const docLink =
+  ' Please see https://docs.launchdarkly.com/sdk/client-side/javascript#initializing-the-client for instructions on SDK initialization.';
+
+const clientNotReady = function() {
+  return 'LaunchDarkly client is not ready';
+};
+
+const eventCapacityExceeded = function() {
+  return 'Exceeded event queue capacity. Increase capacity to avoid dropping events.';
+};
+
+const eventWithoutUser = function() {
+  return 'Be sure to call `identify` in the LaunchDarkly client: https://docs.launchdarkly.com/sdk/features/identify#javascript';
+};
+
+const invalidContentType = function(contentType) {
+  return 'Expected application/json content type but got "' + contentType + '"';
+};
+
+const invalidKey = function() {
+  return 'Event key must be a string';
+};
+
+const localStorageUnavailable = function(err) {
+  return 'local storage is unavailable: ' + errorString(err);
+};
+
+const networkError = e => 'network error' + (e ? ' (' + e + ')' : '');
+
+// We should remove unknownCustomEventKey in the future - see comments in track() in index.js
+const unknownCustomEventKey = function(key) {
+  return 'Custom event "' + key + '" does not exist';
+};
+
+const environmentNotFound = function() {
+  return 'Environment not found. Double check that you specified a valid environment/client-side ID.' + docLink;
+};
+
+const environmentNotSpecified = function() {
+  return 'No environment/client-side ID was specified.' + docLink;
+};
+
+const errorFetchingFlags = function(err) {
+  return 'Error fetching flag settings: ' + errorString(err);
+};
+
+const userNotSpecified = function() {
+  return 'No user specified.' + docLink;
+};
+
+const invalidUser = function() {
+  return 'Invalid user specified.' + docLink;
+};
+
+const bootstrapOldFormat = function() {
+  return (
+    'LaunchDarkly client was initialized with bootstrap data that did not include flag metadata. ' +
+    'Events may not be sent correctly.' +
+    docLink
+  );
+};
+
+const bootstrapInvalid = function() {
+  return 'LaunchDarkly bootstrap data is not available because the back end could not read the flags.';
+};
+
+const deprecated = function(oldName, newName) {
+  if (newName) {
+    return '"' + oldName + '" is deprecated, please use "' + newName + '"';
+  }
+  return '"' + oldName + '" is deprecated';
+};
+
+const httpErrorMessage = function(status, context, retryMessage) {
+  return (
+    'Received error ' +
+    status +
+    (status === 401 ? ' (invalid SDK key)' : '') +
+    ' for ' +
+    context +
+    ' - ' +
+    (errors.isHttpErrorRecoverable(status) ? retryMessage : 'giving up permanently')
+  );
+};
+
+const httpUnavailable = function() {
+  return 'Cannot make HTTP requests in this environment.' + docLink;
+};
+
+const identifyDisabled = function() {
+  return 'identify() has no effect here; it must be called on the main client instance';
+};
+
+const streamClosing = function() {
+  return 'Closing stream connection';
+};
+
+const streamConnecting = function(url) {
+  return 'Opening stream connection to ' + url;
+};
+
+const streamError = function(err, streamReconnectDelay) {
+  return (
+    'Error on stream connection: ' +
+    errorString(err) +
+    ', will continue retrying every ' +
+    streamReconnectDelay +
+    ' milliseconds.'
+  );
+};
+
+const unknownOption = name => 'Ignoring unknown config option "' + name + '"';
+
+const wrongOptionType = (name, expectedType, actualType) =>
+  'Config option "' + name + '" should be of type ' + expectedType + ', got ' + actualType + ', using default value';
+
+const wrongOptionTypeBoolean = (name, actualType) =>
+  'Config option "' + name + '" should be a boolean, got ' + actualType + ', converting to boolean';
+
+const optionBelowMinimum = (name, value, minimum) =>
+  'Config option "' + name + '" was set to ' + value + ', changing to minimum value of ' + minimum;
+
+const debugPolling = function(url) {
+  return 'polling for feature flags at ' + url;
+};
+
+const debugStreamPing = function() {
+  return 'received ping message from stream';
+};
+
+const debugStreamPut = function() {
+  return 'received streaming update for all flags';
+};
+
+const debugStreamPatch = function(key) {
+  return 'received streaming update for flag "' + key + '"';
+};
+
+const debugStreamPatchIgnored = function(key) {
+  return 'received streaming update for flag "' + key + '" but ignored due to version check';
+};
+
+const debugStreamDelete = function(key) {
+  return 'received streaming deletion for flag "' + key + '"';
+};
+
+const debugStreamDeleteIgnored = function(key) {
+  return 'received streaming deletion for flag "' + key + '" but ignored due to version check';
+};
+
+const debugEnqueueingEvent = function(kind) {
+  return 'enqueueing "' + kind + '" event';
+};
+
+const debugPostingEvents = function(count) {
+  return 'sending ' + count + ' events';
+};
+
+const debugPostingDiagnosticEvent = function(event) {
+  return 'sending diagnostic event (' + event.kind + ')';
+};
+
+module.exports = {
+  bootstrapInvalid,
+  bootstrapOldFormat,
+  clientInitialized,
+  clientNotReady,
+  debugEnqueueingEvent,
+  debugPostingDiagnosticEvent,
+  debugPostingEvents,
+  debugStreamDelete,
+  debugStreamDeleteIgnored,
+  debugStreamPatch,
+  debugStreamPatchIgnored,
+  debugStreamPing,
+  debugPolling,
+  debugStreamPut,
+  deprecated,
+  environmentNotFound,
+  environmentNotSpecified,
+  errorFetchingFlags,
+  eventCapacityExceeded,
+  eventWithoutUser,
+  httpErrorMessage,
+  httpUnavailable,
+  identifyDisabled,
+  invalidContentType,
+  invalidKey,
+  invalidUser,
+  localStorageUnavailable,
+  networkError,
+  optionBelowMinimum,
+  streamClosing,
+  streamConnecting,
+  streamError,
+  unknownCustomEventKey,
+  unknownOption,
+  userNotSpecified,
+  wrongOptionType,
+  wrongOptionTypeBoolean,
+};

package/src/promiseCoalescer.js

@@ -0,0 +1,52 @@
+// This function allows a series of Promises to be coalesced such that only the most recently
+// added one actually matters. For instance, if several HTTP requests are made to the same
+// endpoint and we want to ensure that whoever made each one always gets the latest data, each
+// can be passed to addPromise (on the same coalescer) and each caller can wait on the
+// coalescer.resultPromise; all three will then receive the result (or error) from the *last*
+// request, and the results of the first two will be discarded.
+//
+// The cancelFn callback, if present, will be called whenever an existing promise is being
+// discarded. This can be used for instance to abort an HTTP request that's now obsolete.
+//
+// The finallyFn callback, if present, is called on completion of the whole thing. This is
+// different from calling coalescer.resultPromise.finally() because it is executed before any
+// other handlers. Its purpose is to tell the caller that this coalescer should no longer be used.
+
+function promiseCoalescer(finallyFn) {
+  let currentPromise;
+  let currentCancelFn;
+  let finalResolve;
+  let finalReject;
+
+  const coalescer = {};
+
+  coalescer.addPromise = (p, cancelFn) => {
+    currentPromise = p;
+    currentCancelFn && currentCancelFn();
+    currentCancelFn = cancelFn;
+
+    p.then(
+      result => {
+        if (currentPromise === p) {
+          finalResolve(result);
+          finallyFn && finallyFn();
+        }
+      },
+      error => {
+        if (currentPromise === p) {
+          finalReject(error);
+          finallyFn && finallyFn();
+        }
+      }
+    );
+  };
+
+  coalescer.resultPromise = new Promise((resolve, reject) => {
+    finalResolve = resolve;
+    finalReject = reject;
+  });
+
+  return coalescer;
+}
+
+module.exports = promiseCoalescer;

package/src/utils.js

@@ -0,0 +1,214 @@
+const base64 = require('base64-js');
+const fastDeepEqual = require('fast-deep-equal');
+
+const userAttrsToStringify = ['key', 'secondary', 'ip', 'country', 'email', 'firstName', 'lastName', 'avatar', 'name'];
+
+// See http://ecmanaut.blogspot.com/2006/07/encoding-decoding-utf8-in-javascript.html
+function btoa(s) {
+  const escaped = unescape(encodeURIComponent(s));
+  return base64.fromByteArray(stringToBytes(escaped));
+}
+
+function stringToBytes(s) {
+  const b = [];
+  for (let i = 0; i < s.length; i++) {
+    b.push(s.charCodeAt(i));
+  }
+  return b;
+}
+
+function base64URLEncode(s) {
+  return (
+    btoa(s)
+      // eslint-disable-next-line
+      .replace(/=/g, '')
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+  );
+}
+
+function clone(obj) {
+  return JSON.parse(JSON.stringify(obj));
+}
+
+function deepEquals(a, b) {
+  return fastDeepEqual(a, b);
+}
+
+// Events emitted in LDClient's initialize method will happen before the consumer
+// can register a listener, so defer them to next tick.
+function onNextTick(cb) {
+  setTimeout(cb, 0);
+}
+
+/**
+ * Wrap a promise to invoke an optional callback upon resolution or rejection.
+ *
+ * This function assumes the callback follows the Node.js callback type: (err, value) => void
+ *
+ * If a callback is provided:
+ *   - if the promise is resolved, invoke the callback with (null, value)
+ *   - if the promise is rejected, invoke the callback with (error, null)
+ *
+ * @param {Promise<any>} promise
+ * @param {Function} callback
+ * @returns Promise<any> | undefined
+ */
+function wrapPromiseCallback(promise, callback) {
+  const ret = promise.then(
+    value => {
+      if (callback) {
+        setTimeout(() => {
+          callback(null, value);
+        }, 0);
+      }
+      return value;
+    },
+    error => {
+      if (callback) {
+        setTimeout(() => {
+          callback(error, null);
+        }, 0);
+      } else {
+        return Promise.reject(error);
+      }
+    }
+  );
+
+  return !callback ? ret : undefined;
+}
+
+/**
+ * Takes a map of flag keys to values, and returns the more verbose structure used by the
+ * client stream.
+ */
+function transformValuesToVersionedValues(flags) {
+  const ret = {};
+  for (const key in flags) {
+    if (objectHasOwnProperty(flags, key)) {
+      ret[key] = { value: flags[key], version: 0 };
+    }
+  }
+  return ret;
+}
+
+/**
+ * Converts the internal flag state map to a simple map of flag keys to values.
+ */
+function transformVersionedValuesToValues(flagsState) {
+  const ret = {};
+  for (const key in flagsState) {
+    if (objectHasOwnProperty(flagsState, key)) {
+      ret[key] = flagsState[key].value;
+    }
+  }
+  return ret;
+}
+
+/**
+ * Returns an array of event groups each of which can be safely URL-encoded
+ * without hitting the safe maximum URL length of certain browsers.
+ *
+ * @param {number} maxLength maximum URL length targeted
+ * @param {Array[Object}]} events queue of events to divide
+ * @returns Array[Array[Object]]
+ */
+function chunkUserEventsForUrl(maxLength, events) {
+  const allEvents = events.slice(0);
+  const allChunks = [];
+  let remainingSpace = maxLength;
+  let chunk;
+
+  while (allEvents.length > 0) {
+    chunk = [];
+
+    while (remainingSpace > 0) {
+      const event = allEvents.shift();
+      if (!event) {
+        break;
+      }
+      remainingSpace = remainingSpace - base64URLEncode(JSON.stringify(event)).length;
+      // If we are over the max size, put this one back on the queue
+      // to try in the next round, unless this event alone is larger
+      // than the limit, in which case, screw it, and try it anyway.
+      if (remainingSpace < 0 && chunk.length > 0) {
+        allEvents.unshift(event);
+      } else {
+        chunk.push(event);
+      }
+    }
+
+    remainingSpace = maxLength;
+    allChunks.push(chunk);
+  }
+
+  return allChunks;
+}
+
+function getLDUserAgentString(platform) {
+  const version = platform.version || VERSION;
+  return platform.userAgent + '/' + version;
+}
+
+function getLDHeaders(platform, options) {
+  if (options && !options.sendLDHeaders) {
+    return {};
+  }
+  const h = {};
+  h[platform.userAgentHeaderName || 'User-Agent'] = getLDUserAgentString(platform);
+  if (options && options.wrapperName) {
+    h['X-LaunchDarkly-Wrapper'] = options.wrapperVersion
+      ? options.wrapperName + '/' + options.wrapperVersion
+      : options.wrapperName;
+  }
+  return h;
+}
+
+function transformHeaders(headers, options) {
+  if (!options || !options.requestHeaderTransform) {
+    return headers;
+  }
+  return options.requestHeaderTransform({ ...headers });
+}
+
+function extend(...objects) {
+  return objects.reduce((acc, obj) => ({ ...acc, ...obj }), {});
+}
+
+function objectHasOwnProperty(object, name) {
+  return Object.prototype.hasOwnProperty.call(object, name);
+}
+
+function sanitizeUser(user) {
+  if (!user) {
+    return user;
+  }
+  let newUser;
+  for (const i in userAttrsToStringify) {
+    const attr = userAttrsToStringify[i];
+    const value = user[attr];
+    if (value !== undefined && typeof value !== 'string') {
+      newUser = newUser || { ...user };
+      newUser[attr] = String(value);
+    }
+  }
+  return newUser || user;
+}
+
+module.exports = {
+  base64URLEncode,
+  btoa,
+  chunkUserEventsForUrl,
+  clone,
+  deepEquals,
+  extend,
+  getLDHeaders,
+  getLDUserAgentString,
+  objectHasOwnProperty,
+  onNextTick,
+  sanitizeUser,
+  transformHeaders,
+  transformValuesToVersionedValues,
+  transformVersionedValuesToValues,
+  wrapPromiseCallback,
+};

package/test-types.ts

@@ -0,0 +1,96 @@
+
+// This file exists only so that we can run the TypeScript compiler in the CI build
+// to validate our typings.d.ts file.
+
+import * as ld from 'launchdarkly-js-sdk-common';
+
+var ver: string = ld.version;
+
+var userWithKeyOnly: ld.LDUser = { key: 'user' };
+var anonUserWithNoKey: ld.LDUser = { anonymous: true };
+var anonUserWithKey: ld.LDUser = { key: 'anon-user', anonymous: true };
+var user: ld.LDUser = {
+  key: 'user',
+  secondary: 'otherkey',
+  name: 'name',
+  firstName: 'first',
+  lastName: 'last',
+  email: 'test@example.com',
+  avatar: 'http://avatar.url',
+  ip: '1.1.1.1',
+  country: 'us',
+  anonymous: true,
+  custom: {
+    'a': 's',
+    'b': true,
+    'c': 3,
+    'd': [ 'x', 'y' ],
+    'e': [ true, false ],
+    'f': [ 1, 2 ]
+  },
+  privateAttributeNames: [ 'name', 'email' ]
+};
+var logger: ld.LDLogger = ld.commonBasicLogger({ level: 'info' });
+var allBaseOptions: ld.LDOptionsBase = {
+  bootstrap: { },
+  baseUrl: '',
+  eventsUrl: '',
+  streamUrl: '',
+  streaming: true,
+  useReport: true,
+  sendLDHeaders: true,
+  requestHeaderTransform: (x) => x,
+  evaluationReasons: true,
+  sendEvents: true,
+  allAttributesPrivate: true,
+  privateAttributeNames: [ 'x' ],
+  inlineUsersInEvents: true,
+  allowFrequentDuplicateEvents: true,
+  sendEventsOnlyForVariation: true,
+  flushInterval: 1,
+  streamReconnectDelay: 1,
+  logger: logger
+};
+
+var client: ld.LDClientBase = {} as ld.LDClientBase;  // wouldn't do this in real life, it's just so the following statements will compile
+
+client.waitUntilReady().then(() => {});
+client.waitForInitialization().then(() => {});
+
+client.identify(user).then(() => {});
+client.identify(user, undefined, () => {});
+client.identify(user, 'hash').then(() => {});
+
+client.alias(user, anonUserWithKey);
+
+var user: ld.LDUser = client.getUser();
+
+client.flush(() => {});
+client.flush().then(() => {});
+
+var boolFlagValue: ld.LDFlagValue = client.variation('key', false);
+var numberFlagValue: ld.LDFlagValue = client.variation('key', 2);
+var stringFlagValue: ld.LDFlagValue = client.variation('key', 'default');
+var jsonFlagValue: ld.LDFlagValue = client.variation('key', [ 'a', 'b' ]);
+
+var detail: ld.LDEvaluationDetail = client.variationDetail('key', 'default');
+var detailValue: ld.LDFlagValue = detail.value;
+var detailIndex: number | undefined = detail.variationIndex;
+var detailReason: ld.LDEvaluationReason | undefined = detail.reason;
+
+client.setStreaming(true);
+client.setStreaming();
+
+function handleEvent() {}
+client.on('event', handleEvent);
+client.off('event', handleEvent);
+
+client.track('event');
+client.track('event', { someData: 'x' });
+client.track('event', null, 3.5);
+
+var flagSet: ld.LDFlagSet = client.allFlags();
+var flagSetValue: ld.LDFlagValue = flagSet['key'];
+
+client.close(() => {});
+client.close().then(() => {});

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "strict": true,
+    "lib": [
+      "es6"
+    ]
+  },
+  "files": [
+    "typings.d.ts",
+    "test-types.ts"
+  ]
+}