iureiure 1.0.0

package/packages/analytics-js/src/services/PluginEngine/PluginEngine.ts

@@ -0,0 +1,200 @@
+import { isFunction } from '@rudderstack/analytics-js-common/utilities/checks';
+import { getValueByPath, hasValueByPath } from '@rudderstack/analytics-js-common/utilities/object';
+import type {
+  ExtensionPlugin,
+  IPluginEngine,
+  PluginEngineConfig,
+} from '@rudderstack/analytics-js-common/types/PluginEngine';
+import type { ILogger } from '@rudderstack/analytics-js-common/types/Logger';
+import type { Nullable } from '@rudderstack/analytics-js-common/types/Nullable';
+import { PLUGIN_ENGINE } from '@rudderstack/analytics-js-common/constants/loggerContexts';
+import { defaultLogger } from '../Logger';
+import {
+  PLUGIN_ALREADY_EXISTS_ERROR,
+  PLUGIN_DEPS_ERROR,
+  PLUGIN_ENGINE_BUG_ERROR,
+  PLUGIN_EXT_POINT_INVALID_ERROR,
+  PLUGIN_EXT_POINT_MISSING_ERROR,
+  PLUGIN_INVOCATION_ERROR,
+  PLUGIN_NAME_MISSING_ERROR,
+  PLUGIN_NOT_FOUND_ERROR,
+} from '../../constants/logMessages';
+
+// TODO: create chained invoke to take the output frm first plugin and pass
+//  to next or return the value if it is the last one instead of an array per
+//  plugin that is the normal invoke
+// TODO: add invoke method for extension point that we know only one plugin can be used. add invokeMultiple and invokeSingle methods
+class PluginEngine implements IPluginEngine {
+  plugins: ExtensionPlugin[] = [];
+  byName: Record<string, ExtensionPlugin> = {};
+  cache: Record<string, ExtensionPlugin[]> = {};
+  config: PluginEngineConfig = { throws: true };
+  logger?: ILogger;
+
+  constructor(options: PluginEngineConfig = {}, logger?: ILogger) {
+    this.config = {
+      throws: true,
+      ...options,
+    };
+
+    this.logger = logger;
+  }
+
+  register(plugin: ExtensionPlugin, state?: Record<string, any>) {
+    if (!plugin.name) {
+      const errorMessage = PLUGIN_NAME_MISSING_ERROR(PLUGIN_ENGINE);
+      if (this.config.throws) {
+        throw new Error(errorMessage);
+      } else {
+        this.logger?.error(errorMessage, plugin);
+      }
+    }
+
+    if (this.byName[plugin.name]) {
+      const errorMessage = PLUGIN_ALREADY_EXISTS_ERROR(PLUGIN_ENGINE, plugin.name);
+      if (this.config.throws) {
+        throw new Error(errorMessage);
+      } else {
+        this.logger?.error(errorMessage);
+      }
+    }
+
+    this.cache = {};
+    this.plugins = this.plugins.slice();
+    let pos = this.plugins.length;
+
+    this.plugins.forEach((pluginItem: ExtensionPlugin, index: number) => {
+      if (pluginItem.deps?.includes(plugin.name)) {
+        pos = Math.min(pos, index);
+      }
+    });
+
+    this.plugins.splice(pos, 0, plugin);
+
+    this.byName[plugin.name] = plugin;
+
+    if (isFunction(plugin.initialize)) {
+      plugin.initialize(state);
+    }
+  }
+
+  unregister(name: string) {
+    const plugin = this.byName[name];
+
+    if (!plugin) {
+      const errorMessage = PLUGIN_NOT_FOUND_ERROR(PLUGIN_ENGINE, name);
+      if (this.config.throws) {
+        throw new Error(errorMessage);
+      } else {
+        this.logger?.error(errorMessage);
+      }
+    }
+
+    const index = this.plugins.indexOf(plugin as ExtensionPlugin);
+
+    if (index === -1) {
+      const errorMessage = PLUGIN_ENGINE_BUG_ERROR(PLUGIN_ENGINE, name);
+      if (this.config.throws) {
+        throw new Error(errorMessage);
+      } else {
+        this.logger?.error(errorMessage);
+      }
+    }
+
+    this.cache = {};
+    delete this.byName[name];
+    this.plugins = this.plugins.slice();
+    this.plugins.splice(index, 1);
+  }
+
+  getPlugin(name: string): ExtensionPlugin | undefined {
+    return this.byName[name];
+  }
+
+  getPlugins(extPoint?: string): ExtensionPlugin[] {
+    const lifeCycleName = extPoint ?? '.';
+
+    if (!this.cache[lifeCycleName]) {
+      this.cache[lifeCycleName] = this.plugins.filter(plugin => {
+        if (plugin.deps?.some(dependency => !this.byName[dependency])) {
+          // If deps not exist, then not load it.
+          const notExistDeps = plugin.deps.filter(dependency => !this.byName[dependency]);
+          this.logger?.error(PLUGIN_DEPS_ERROR(PLUGIN_ENGINE, plugin.name, notExistDeps));
+          return false;
+        }
+        return lifeCycleName === '.' ? true : hasValueByPath(plugin, lifeCycleName);
+      });
+    }
+
+    return this.cache[lifeCycleName] as ExtensionPlugin[];
+  }
+
+  // This method allows to process this.plugins so that it could
+  // do some unified pre-process before application starts.
+  processRawPlugins(callback: (plugins: ExtensionPlugin[]) => any) {
+    callback(this.plugins);
+    this.cache = {};
+  }
+
+  invoke<T = any>(extPoint?: string, allowMultiple = true, ...args: any[]): Nullable<T>[] {
+    let extensionPointName = extPoint;
+
+    if (!extensionPointName) {
+      throw new Error(PLUGIN_EXT_POINT_MISSING_ERROR);
+    }
+
+    const noCall = extensionPointName.startsWith('!');
+    const throws = this.config.throws ?? extensionPointName.endsWith('!');
+
+    // eslint-disable-next-line unicorn/better-regex
+    extensionPointName = extensionPointName.replace(/(^!|!$)/g, '');
+
+    if (!extensionPointName) {
+      throw new Error(PLUGIN_EXT_POINT_INVALID_ERROR);
+    }
+
+    const extensionPointNameParts = extensionPointName.split('.');
+    extensionPointNameParts.pop();
+
+    const pluginMethodPath = extensionPointNameParts.join('.');
+    const pluginsToInvoke = allowMultiple
+      ? this.getPlugins(extensionPointName)
+      : [this.getPlugins(extensionPointName)[0] as ExtensionPlugin];
+
+    return pluginsToInvoke.map(plugin => {
+      const method = getValueByPath(plugin, extensionPointName as string);
+
+      if (!isFunction(method) || noCall) {
+        return method;
+      }
+
+      try {
+        return method.apply(getValueByPath(plugin, pluginMethodPath), args);
+      } catch (err) {
+        // When a plugin failed, doesn't break the app
+        if (throws) {
+          throw err;
+        } else {
+          this.logger?.error(
+            PLUGIN_INVOCATION_ERROR(PLUGIN_ENGINE, extensionPointName, plugin.name),
+            err,
+          );
+        }
+      }
+
+      return null;
+    });
+  }
+
+  invokeSingle<T = any>(extPoint?: string, ...args: any[]): Nullable<T> {
+    return this.invoke(extPoint, false, ...args)[0];
+  }
+
+  invokeMultiple<T = any>(extPoint?: string, ...args: any[]): Nullable<T>[] {
+    return this.invoke(extPoint, true, ...args);
+  }
+}
+
+const defaultPluginEngine = new PluginEngine({ throws: true }, defaultLogger);
+
+export { PluginEngine, defaultPluginEngine };

package/packages/analytics-js/src/services/PluginEngine/README.md

@@ -0,0 +1,152 @@
+# Overview
+
+Web applications are becoming more and more complicated nowadays. To separate concerns, decouple
+business logic, a large application should be well designed. One of best practices is plugin based
+architecture. Whenever you add a new feature, it should not add much complication to the system so
+that the project could be always maintainable when it grows.
+
+Every plugin in the system maybe not bundled separately but just a logical plugin.
+
+# Extension Points
+
+From above two examples, we have seen how extension points work. It's pretty simple with two parts:
+
+1. Define/use extension point in an extensible module/component.
+2. Define plugin object structure following the extension point.
+
+There isn't any central registry to declare extension points but whenever you need to make some
+logic extensible, you use `plugin.invoke(extPoint)` or `plugin.getPlugins(extPoint)` to get all
+plugins which contributes to the extension point.
+
+An extension point is just a string that represents the plugin object structure separated by `.`.
+
+For example, when we make `Menu` component extensible, we use below code:
+
+```js
+const menuItems = [];
+plugin.invoke('menu.processMenuItems', menuItems);
+// render menuItems to UI...
+```
+
+Then `menuItems` array can be filled by all plugins which contribute to `menu.processMenuItems`.
+
+Below is how plugin consume the extension point:
+
+```js
+plugin.registry({
+  name: 'samplePlugin',
+  menu: {
+    processMenuItems(items) {
+      items.push({ label: 'label', link: 'hello/sample' });
+    },
+  },
+});
+```
+
+Not only application itself but also every plugin could define extension point.
+
+Extension point is usually a method, but could be also just some value. It depends on how extension
+point provider uses it.
+
+# Plugin
+
+Every plugin is just a JavaScript object, normally every path to leaf property means it contribute
+some extension point. Like above example:
+
+```js
+const myPlugin = {
+  name: 'samplePlugin',
+  menu: {
+    processMenuItems(items) {
+      items.push({ label: 'label', link: 'hello/sample' });
+    },
+  },
+};
+```
+
+It defines a plugin named `samplePlugin` and contribute to the extension point `menu.processMenuItems`.
+
+The only mandatory field is `name` which should be unique in an application.
+
+## Plugin Dependency
+
+Every plugin could declare its dependencies by `deps` property:
+
+```js
+const myPlugin = {
+  name: 'myPlugin',
+  deps: ['plugin1', 'plugin2'],
+};
+```
+
+`deps` property does two things:
+
+1. Plugin extension points are executed after its deps when call `plugin.invoke` or `plugin.getPlugins`
+2. If some deps don't exist, then the plugin is also not loaded.
+
+# API Reference
+
+### plugin.register(p)
+
+Register a plugin to the system. Normally you should register all plugins before your app is
+started. If you want to dynamically register plugin on demand, you need to ensure all extension
+points executed again. For example, you may want to `Menu` component force updated when new plugin
+registered.
+
+### plugin.unregister(name)
+
+Unregister a plugin. You may also need to ensure all UI re-rendered if necessary yourself.
+
+### plugin.getPlugin(name)
+
+Get the plugin instance by name. If your plugin want to export some reusable utilities or API to
+other plugins, you can define it in plugin object, then other plugin can use `getPlugin` to get the
+plugin object and call its API.
+
+### plugin.getPlugins(extPoint)
+
+Get all plugins that contributes to the extension point.
+
+### plugin.invoke(extPoint, ...args)
+
+Call extension point method from all plugins which support it and returns an array which contains
+all return value from extension point function.
+
+For example:
+
+```js
+plugin.registery({
+  name: 'p1',
+  getMenuItem() {
+    return 'item1';
+  },
+});
+plugin.registery({
+  name: 'p2',
+  getMenuItem() {
+    return 'item2';
+  },
+});
+plugin.registery({
+  name: 'p3',
+  getMenuItem() {
+    return 'item3';
+  },
+});
+
+const items = plugin.invoke('getMenuItem');
+// items: ['p1', 'p2', 'p3']
+```
+
+If extension point is not a function, then use the value as return value. If you don't want to call
+the extension point but just collect all functions, you can use prefix the extension point
+with `!`, for example:
+
+```js
+plugin.registery({ name: 'p1', rootComponent: () => <div>Hello</div>)
+plugin.registery({ name: 'p2', rootComponent: () => <div>Hello2</div>)
+const rootComponents = plugin.invoke('!rootComponent');
+// rootComponents: [func1, func2]
+```
+
+This is useful if you want to contribute React component to some extension point.

package/packages/analytics-js/src/services/PluginEngine/index.ts

@@ -0,0 +1 @@
+export { PluginEngine, defaultPluginEngine } from './PluginEngine';

package/packages/analytics-js/src/services/StoreManager/Store.ts

@@ -0,0 +1,218 @@
+import { trim } from '@rudderstack/analytics-js-common/utilities/string';
+import { isNullOrUndefined } from '@rudderstack/analytics-js-common/utilities/checks';
+import { stringifyWithoutCircular } from '@rudderstack/analytics-js-common/utilities/json';
+import type { IStorage, IStore, IStoreConfig } from '@rudderstack/analytics-js-common/types/Store';
+import type { IErrorHandler } from '@rudderstack/analytics-js-common/types/ErrorHandler';
+import type { ILogger } from '@rudderstack/analytics-js-common/types/Logger';
+import type { IPluginsManager } from '@rudderstack/analytics-js-common/types/PluginsManager';
+import type { Nullable } from '@rudderstack/analytics-js-common/types/Nullable';
+import { LOCAL_STORAGE, MEMORY_STORAGE } from '@rudderstack/analytics-js-common/constants/storages';
+import { getMutatedError } from '@rudderstack/analytics-js-common/utilities/errors';
+import { defaultLogger } from '../Logger';
+import { defaultErrorHandler } from '../ErrorHandler';
+import { isStorageQuotaExceeded } from '../../components/capabilitiesManager/detection';
+import {
+  STORAGE_QUOTA_EXCEEDED_WARNING,
+  STORE_DATA_FETCH_ERROR,
+  STORE_DATA_SAVE_ERROR,
+} from '../../constants/logMessages';
+import { getStorageEngine } from './storages/storageEngine';
+
+/**
+ * Store Implementation with dedicated storage
+ */
+class Store implements IStore {
+  id: string;
+  name: string;
+  isEncrypted: boolean;
+  validKeys: Record<string, string>;
+  engine: IStorage;
+  originalEngine: IStorage;
+  noKeyValidation?: boolean;
+  noCompoundKey?: boolean;
+  errorHandler?: IErrorHandler;
+  hasErrorHandler = false;
+  logger?: ILogger;
+  pluginsManager?: IPluginsManager;
+
+  constructor(config: IStoreConfig, engine?: IStorage, pluginsManager?: IPluginsManager) {
+    this.id = config.id;
+    this.name = config.name;
+    this.isEncrypted = config.isEncrypted ?? false;
+    this.validKeys = config.validKeys ?? {};
+    this.engine = engine ?? getStorageEngine(LOCAL_STORAGE);
+    this.noKeyValidation = Object.keys(this.validKeys).length === 0;
+    this.noCompoundKey = config.noCompoundKey;
+    this.originalEngine = this.engine;
+    this.errorHandler = config.errorHandler ?? defaultErrorHandler;
+    this.hasErrorHandler = Boolean(this.errorHandler);
+    this.logger = config.logger ?? defaultLogger;
+    this.pluginsManager = pluginsManager;
+  }
+
+  /**
+   * Ensure the key is valid and with correct format
+   */
+  createValidKey(key: string): string | undefined {
+    const { name, id, validKeys, noKeyValidation, noCompoundKey } = this;
+
+    if (noKeyValidation) {
+      return noCompoundKey ? key : [name, id, key].join('.');
+    }
+
+    // validate and return undefined if invalid key
+    let compoundKey;
+    Object.values(validKeys).forEach(validKeyName => {
+      if (validKeyName === key) {
+        compoundKey = noCompoundKey ? key : [name, id, key].join('.');
+      }
+    });
+
+    return compoundKey;
+  }
+
+  /**
+   * Switch to inMemoryEngine, bringing any existing data with.
+   */
+  swapQueueStoreToInMemoryEngine() {
+    const { name, id, validKeys, noCompoundKey } = this;
+    const inMemoryStorage = getStorageEngine(MEMORY_STORAGE);
+
+    // grab existing data, but only for this page's queue instance, not all
+    // better to keep other queues in localstorage to be flushed later
+    // than to pull them into memory and remove them from durable storage
+    Object.keys(validKeys).forEach(key => {
+      const value = this.get(validKeys[key] as string);
+      const validKey = noCompoundKey ? key : [name, id, key].join('.');
+
+      inMemoryStorage.setItem(validKey, value);
+      // TODO: are we sure we want to drop clientData
+      //  if cookies are not available and localstorage is full?
+      this.remove(key);
+    });
+
+    this.engine = inMemoryStorage;
+  }
+
+  /**
+   * Set value by key.
+   */
+  set(key: string, value: any) {
+    const validKey = this.createValidKey(key);
+
+    if (!validKey) {
+      return;
+    }
+
+    try {
+      // storejs that is used in localstorage engine already stringifies json
+      this.engine.setItem(
+        validKey,
+        this.encrypt(stringifyWithoutCircular(value, false, [], this.logger)),
+      );
+    } catch (err) {
+      if (isStorageQuotaExceeded(err)) {
+        this.logger?.warn(STORAGE_QUOTA_EXCEEDED_WARNING(`Store ${this.id}`));
+        // switch to inMemory engine
+        this.swapQueueStoreToInMemoryEngine();
+        // and save it there
+        this.set(key, value);
+      } else {
+        this.onError(getMutatedError(err, STORE_DATA_SAVE_ERROR(key)));
+      }
+    }
+  }
+
+  /**
+   * Get by Key.
+   */
+  get<T = any>(key: string): Nullable<T> {
+    const validKey = this.createValidKey(key);
+
+    try {
+      if (!validKey) {
+        return null;
+      }
+
+      const str = this.decrypt(this.engine.getItem(validKey));
+
+      if (isNullOrUndefined(str)) {
+        return null;
+      }
+
+      // storejs that is used in localstorage engine already deserializes json strings but swallows errors
+      return JSON.parse(str as string);
+    } catch (err) {
+      this.onError(new Error(`${STORE_DATA_FETCH_ERROR(key)}: ${(err as Error).message}`));
+      return null;
+    }
+  }
+
+  /**
+   * Remove by Key.
+   */
+  remove(key: string) {
+    const validKey = this.createValidKey(key);
+
+    if (validKey) {
+      this.engine.removeItem(validKey);
+    }
+  }
+
+  /**
+   * Get original engine
+   */
+  getOriginalEngine(): IStorage {
+    return this.originalEngine;
+  }
+
+  /**
+   * Decrypt values
+   */
+  decrypt(value?: Nullable<string>): Nullable<string> {
+    if (isNullOrUndefined(value)) {
+      return null;
+    }
+
+    return this.crypto(value as string, 'decrypt');
+  }
+
+  /**
+   * Encrypt value
+   */
+  encrypt(value: Nullable<any>): string {
+    return this.crypto(value, 'encrypt');
+  }
+
+  /**
+   * Extension point to use with encryption plugins
+   */
+  crypto(value: Nullable<any>, mode: 'encrypt' | 'decrypt'): string {
+    const noEncryption =
+      !this.isEncrypted || !value || typeof value !== 'string' || trim(value) === '';
+
+    if (noEncryption) {
+      return value;
+    }
+
+    const extensionPointName = `storage.${mode}`;
+    const formattedValue = this.pluginsManager
+      ? this.pluginsManager.invokeSingle<string>(extensionPointName, value)
+      : value;
+
+    return typeof formattedValue === 'undefined' ? value : formattedValue ?? '';
+  }
+
+  /**
+   * Handle errors
+   */
+  onError(error: unknown) {
+    if (this.hasErrorHandler) {
+      this.errorHandler?.onError(error, `Store ${this.id}`);
+    } else {
+      throw error;
+    }
+  }
+}
+
+export { Store };