@static-suite/static-suite-data-server 0.0.1

package/src/lib/utils/fs/fsUtils.ts

@@ -0,0 +1,141 @@
+import fs from 'fs';
+import fg, { Options as fastGlobOptions } from 'fast-glob';
+import chokidar from 'chokidar';
+import { logger } from '@lib/utils/logger';
+import { parseJsonString } from '@lib/utils/string';
+import { FileType } from './fs.types';
+
+/**
+ * Tells whether a path is JSON or not.
+ *
+ * @remarks
+ * A fast checker that avoids reading the contents of a file, or doing
+ * some other complex operation to determine if a file contains JSON data.
+ *
+ * @internal
+ */
+export const isJsonFile = (filepath: string): boolean =>
+  filepath.slice(-5) === '.json';
+
+/**
+ * Reads a file and logs an error on failure.
+ *
+ * @param filePath - A path to a file.
+ *
+ * @returns The file contents as a string if file is found, or null otherwise.
+ */
+export const readFile = (filePath: string): string | null => {
+  let content = null;
+  try {
+    content = fs.readFileSync(filePath, { encoding: 'utf8', flag: 'r' });
+  } catch (error) {
+    // When an error is thrown, content is undefined, so ensure
+    // it is converted to null.
+    content = null;
+    logger.error(`Error reading file "${filePath}": ${error}`);
+  }
+  return content;
+};
+
+/**
+ * Gets raw and JSON parsed content from a file.
+ *
+ * @param filepath - A path to a file.
+ *
+ * @returns Object with two properties, "raw" and "json", which contain
+ * the raw and json version of the file. If file is not a JSON, the "json"
+ * property is null. If file is not found, both properties are null.
+ */
+export const getFileContent = (filepath: string): FileType => {
+  const raw = readFile(filepath);
+  let json = null;
+  if (raw && isJsonFile(filepath)) {
+    json = parseJsonString(raw);
+    if (!json) {
+      logger.error(`Error getting JSON from file "${filepath}"`);
+    }
+  }
+  return { raw, json };
+};
+
+/**
+ * Finds all files inside a directory
+ *
+ * @param dir - Absolute path to the directory to be scanned
+ * @param glob - Optional glob to filter results (default all files recursive '**\/*')
+ * @param options - Options for the fast-glob package.
+ * See https://www.npmjs.com/package/fast-glob for reference .
+ *
+ * @returns Array of file paths found inside directory
+ */
+export const findFilesInDir = (
+  dir: string,
+  glob = '**/*',
+  options: fastGlobOptions = { absolute: false },
+): string[] => {
+  const startDate = Date.now();
+  const files = fg.sync([glob], { cwd: dir, ...options });
+  const endDate = Date.now();
+  logger.debug(
+    `${files.length} files found inside ${dir} in ${endDate - startDate}ms.`,
+  );
+  return files;
+};
+
+/**
+ * Gets a file's modification date and logs an error on failure.
+ *
+ * @param filePath - Path to the file
+ *
+ * @returns The file's modification date as a Date object, or null on error
+ */
+export const getModificationDate = (filePath: string): Date | null => {
+  let modificationDate = null;
+  try {
+    modificationDate = new Date(fs.statSync(filePath).mtime);
+  } catch (e) {
+    logger.error(`Error getting modification date for ${`path`}: ${e}`);
+  }
+  return modificationDate;
+};
+
+/**
+ * Watches for changes on a set of paths and attach listener to them
+ *
+ * @remarks
+ * It handles three different events: add, change and unlink
+ *
+ * @param paths - An array of paths to be watched
+ * @param listeners - An object with three optional event keys (add, change and unlink)
+ * and a listener function as value. That function will be executed once any of
+ * the event keys is dispatched.
+ */
+export const watch = (
+  paths: string[],
+  listeners: Record<'add' | 'change' | 'unlink', (filePath: string) => void>,
+): void => {
+  if (paths.length > 0) {
+    const watcher = chokidar.watch(paths, {
+      ignored: /(^|[/\\])\../,
+      persistent: true,
+    });
+
+    // Add event listeners.
+    watcher.on('ready', () => {
+      logger.debug(`Watcher listening for changes on ${paths.join(',')}`);
+      watcher
+        .on('add', filePath => {
+          logger.debug(`File ${filePath} added`);
+          listeners.add(filePath);
+        })
+        .on('change', filePath => {
+          logger.debug(`File ${filePath} changed`);
+          listeners.change(filePath);
+        })
+        .on('unlink', filePath => {
+          logger.debug(`File ${filePath} removed`);
+          listeners.unlink(filePath);
+        });
+    });
+  }
+};

package/src/lib/utils/fs/index.ts

@@ -0,0 +1 @@
+export * from './fsUtils';

package/src/lib/utils/logger/__tests__/logger.test.ts

@@ -0,0 +1,12 @@
+import { logger } from '@lib/utils/logger';
+
+describe('Logger utils test', () => {
+  describe('logger', () => {
+    it('is an object with at least four functions: error, warn, info and debug', () => {
+      expect(typeof logger.error).toBe('function');
+      expect(typeof logger.warn).toBe('function');
+      expect(typeof logger.info).toBe('function');
+      expect(typeof logger.debug).toBe('function');
+    });
+  });
+});

package/src/lib/utils/logger/index.ts

@@ -0,0 +1 @@
+export * from './logger';

package/src/lib/utils/logger/logger.ts

@@ -0,0 +1,87 @@
+import fs from 'fs';
+import path from 'path';
+import winston from 'winston';
+import { LogLevel, LogFile } from './logger.types';
+
+/**
+ * Defines a custom log format that prints a timestamp, a level and a message
+ */
+const customFormat = winston.format.printf(
+  ({ level, message, timestamp }) => `${timestamp} [${level}]: ${message}`,
+);
+
+/**
+ * The combined log format, that makes use of the custom log format
+ */
+const combinedFormat = winston.format.combine(
+  winston.format.timestamp(),
+  customFormat,
+);
+
+/**
+ * The winston logger
+ */
+export const logger: winston.Logger = winston.createLogger({
+  levels: winston.config.npm.levels,
+  level: 'info',
+  format: winston.format.json(),
+  transports: [
+    // Write all logs with level `info` and below to console
+    new winston.transports.Console({
+      format: combinedFormat,
+    }),
+  ],
+});
+
+/**
+ * Configures a logger instance
+ *
+ * @remarks
+ * The logger can log its messages to two different transports:
+ *
+ * 1) The stdout (from the terminal/console which started this process)
+ * 2) A log file located on the filesystem
+ *
+ * Since stdout is a volatile transport that cannot be reviewed at a
+ * later point in time, it is recommended to use the log file when
+ * running the Data Server on production environments.
+ *
+ * If a log file is defined, but its path is no writable, it should:
+ * 1) Log an error (which would be logged to the stdout)
+ * 2) Throw an error
+ *
+ * @param level - Log level, defaults to "warn"
+ * @param logFile - Configuration data for the log file. An object
+ * containing two properties: path and level
+ *
+ * @throws
+ * An exception if a log file is defined, but its path is no writable
+ */
+export const configureLogger = (
+  level: LogLevel = LogLevel.WARN,
+  logFile?: LogFile,
+): void => {
+  if (level) {
+    logger.level = level;
+  }
+  if (logFile && logFile.path) {
+    const logFileAbsolute = fs.realpathSync(path.resolve(logFile.path));
+    // Check if file dirname is writable.
+    try {
+      fs.accessSync(path.dirname(logFileAbsolute), fs.constants.W_OK);
+    } catch (e) {
+      // Log error and rethrow.
+      logger.error(`Log file "${logFileAbsolute}" is not writable: ${e}`);
+      throw e;
+    }
+
+    // Create and add the file transport to the logger
+    const fileTransport = new winston.transports.File({
+      filename: path.basename(logFileAbsolute),
+      dirname: path.dirname(logFileAbsolute),
+      format: combinedFormat,
+      level: logFile.level,
+    });
+    logger.add(fileTransport);
+  }
+};

package/src/lib/utils/logger/logger.types.ts

@@ -0,0 +1,41 @@
+import winston from 'winston';
+
+/**
+ * The logger service.
+ *
+ * @remarks
+ * A logger currently based on the "winston" package.
+ */
+export type Logger = winston.Logger;
+
+/**
+ * Log levels: error, warn, info and debug.
+ *
+ * @public
+ */
+export enum LogLevel {
+  ERROR = 'error',
+  WARN = 'warn',
+  INFO = 'info',
+  DEBUG = 'debug',
+}
+
+/**
+ * A helper to get LogLevel type as strings. @see {@link LogLevel}.
+ */
+export type LogLevelStrings = keyof typeof LogLevel;
+
+/**
+ * A log file definition.
+ */
+export type LogFile = {
+  /**
+   * Path to the log file.
+   */
+  path: string;
+
+  /**
+   * Log level for the log file.
+   */
+  level: LogLevel;
+};

package/src/lib/utils/module/__mocks__/dummyModule.query.js

@@ -0,0 +1,4 @@
+module.exports = {
+  dummyModule: () => 'dummyModuleValue',
+  dummyObject: { key: 'dummyModuleValue' },
+};

package/src/lib/utils/module/__mocks__/dummyModule2.query.js

@@ -0,0 +1,4 @@
+module.exports = {
+  dummyModule2: () => 'dummyModule2Value',
+  dummyObject2: { key: 'dummyModule2Value' },
+};

package/src/lib/utils/module/__tests__/dirBasedModuleGroupManager.test.ts

@@ -0,0 +1,34 @@
+import fs from 'fs';
+import path from 'path';
+import { config } from '@lib/config';
+import { dirBasedModuleGroupManager } from '@lib/utils/module';
+
+config.queryDir = fs.realpathSync(
+  path.resolve(path.join(__dirname, '../__mocks__')),
+);
+export const exampleQueryManager = dirBasedModuleGroupManager('query');
+
+describe('dirBasedModuleGroupManager test', () => {
+  describe('getModuleGroupInfo', () => {
+    it('loads a directory of modules', () => {
+      const moduleGroupInfo = exampleQueryManager.getModuleGroupInfo();
+      expect(moduleGroupInfo.size).toBe(2);
+      expect(Array.from(moduleGroupInfo.keys())).toStrictEqual([
+        'dummyModule',
+        'dummyModule2',
+      ]);
+      expect(moduleGroupInfo.get('dummyModule')).not.toBe(null);
+      expect(moduleGroupInfo.get('dummyModule2')).not.toBe(null);
+    });
+  });
+
+  describe('reset', () => {
+    it('resets a directory of modules', () => {
+      const moduleGroupInfo = exampleQueryManager.getModuleGroupInfo();
+      expect(moduleGroupInfo.size).toBe(2);
+
+      exampleQueryManager.reset();
+      expect(moduleGroupInfo.size).toBe(0);
+    });
+  });
+});

package/src/lib/utils/module/__tests__/moduleHandler.test.ts

@@ -0,0 +1,100 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+/* eslint-disable global-require */
+import fs from 'fs';
+import path from 'path';
+import { logger } from '@lib/utils/logger';
+import { moduleManager } from '../moduleManager';
+
+// This works in conjunction with "__mocks__/clear-module.js"
+jest.mock('clear-module');
+
+const dummyModulePath = fs.realpathSync(
+  path.resolve(path.join(__dirname, '../__mocks__/dummyModule.query.js')),
+);
+
+beforeEach(() => {
+  logger.error = jest.fn();
+});
+
+describe('moduleHandler test', () => {
+  describe('get', () => {
+    describe('when a module exists', () => {
+      it('gets a module without logging any error', () => {
+        const { dummyObject } = moduleManager.get(dummyModulePath);
+
+        expect(dummyObject.key).toBe('dummyModuleValue');
+        expect(logger.error).not.toHaveBeenCalled();
+      });
+
+      it('gets a module twice without reloading it', () => {
+        const { dummyObject: firstDummyObject } =
+          moduleManager.get(dummyModulePath);
+        expect(firstDummyObject.key).toBe('dummyModuleValue');
+        firstDummyObject.key = 'updatedDummyModuleValue';
+        const { dummyObject: secondDummyObject } =
+          moduleManager.get(dummyModulePath);
+        expect(secondDummyObject.key).toBe('updatedDummyModuleValue');
+      });
+    });
+
+    describe('when a module does not exist', () => {
+      it('throws an exception and logs an error', () => {
+        expect(() => moduleManager.get('invalid-path')).toThrow();
+        expect(logger.error).toHaveBeenCalled();
+      });
+    });
+  });
+
+  describe('load', () => {
+    describe('when a module exists', () => {
+      it('loads a module without logging any error', () => {
+        const { dummyObject } = moduleManager.load(dummyModulePath);
+        expect(dummyObject.key).toBe('dummyModuleValue');
+        expect(logger.error).not.toHaveBeenCalled();
+      });
+
+      it('loads a module twice reloading it from scratch', () => {
+        const { dummyObject: firstDummyObject } =
+          moduleManager.load(dummyModulePath);
+        const { dummyObject: secondDummyObject } =
+          moduleManager.load(dummyModulePath);
+
+        firstDummyObject.key = 'updatedDummyModuleValue';
+
+        expect(firstDummyObject.key).toBe('updatedDummyModuleValue');
+        expect(secondDummyObject.key).toBe('dummyModuleValue');
+      });
+    });
+    describe('when a module does not exist', () => {
+      it('throws an exception and logs an error', () => {
+        expect(() => moduleManager.get('invalid-path')).toThrow();
+        expect(logger.error).toHaveBeenCalled();
+      });
+    });
+  });
+
+  describe('remove', () => {
+    it('removes a single module from Node.js cache', () => {
+      const { dummyObject: firstDummyObject } =
+        moduleManager.get(dummyModulePath);
+      moduleManager.remove(dummyModulePath);
+      const { dummyObject: secondDummyObject } =
+        moduleManager.get(dummyModulePath);
+      firstDummyObject.key = 'updatedDummyModuleValue';
+      expect(firstDummyObject.key).toBe('updatedDummyModuleValue');
+      expect(secondDummyObject.key).toBe('dummyModuleValue');
+    });
+  });
+
+  describe('removeAll', () => {
+    it('removes several modules from Node.js cache', () => {
+      const { dummyObject: dummyObject1 } = moduleManager.get(dummyModulePath);
+      dummyObject1.key = 'updatedDummyModuleValue';
+      moduleManager.removeAll(/dummyModule/);
+      const { dummyObject: dummyObject2 } = moduleManager.get(dummyModulePath);
+
+      expect(dummyObject1.key).toBe('updatedDummyModuleValue');
+      expect(dummyObject2.key).toBe('dummyModuleValue');
+    });
+  });
+});

package/src/lib/utils/module/dirBasedModuleGroupManager.ts

@@ -0,0 +1,78 @@
+import path from 'path';
+import { config } from '@lib/config';
+import { findFilesInDir } from '@lib/utils/fs';
+import { cache } from '@lib/utils/cache';
+import { moduleManager } from './moduleManager';
+import { ModuleGroupManager, ModuleInfo } from './module.types';
+
+/**
+ * A manager of module groups based on a directory.
+ *
+ * A module group is a set of user-land modules that are stored inside
+ * a directory. The contents of that directory are unknown, and it can contain
+ * modules and other non-module files required by those modules.
+ *
+ * Modules are distinguished from other files because they contain a key as a suffix,
+ * at the end of their name, following this pattern: [MODULE_ID].[KEY].js
+ *
+ * For example:
+ *
+ * - lastContents.query.js
+ * - listByTermId.query.js
+ * - taxonomy.hook.js
+ * - media.hook.js
+ *
+ * This manager provided a set of common functionalities for those kind of
+ * directories.
+ *
+ * @param key - Key to distinguish modules from other files. This key is
+ * also used to derive the name of the configuration option that defines
+ * the path to the directory where the module group is stored, following this
+ * pattern: `${key}Dir`
+ * @returns A module group manager with a set of common functionalities
+ * for those kind of directories.
+ */
+export const dirBasedModuleGroupManager = <ModuleType>(
+  // Key needs to be explicitly defined to make TypeScript happy.
+  key: 'hook' | 'query' | 'task',
+): ModuleGroupManager<ModuleType> => {
+  /**
+   * Cache bin used by this module group
+   */
+  const moduleGroupInfo = cache.bin<ModuleInfo<ModuleType>>(`${key}-modules`);
+
+  const moduleGroupManager = {
+    getModuleGroupInfo: (): Map<string, ModuleInfo<ModuleType>> => {
+      // Use config here, because outside this function, the config object is not
+      // already defined.
+      const dir = config[`${key}Dir`];
+      // Scan directory only if moduleGroupInfo is empty.
+      if (dir && moduleGroupInfo.size === 0) {
+        // For each detected module, get all its information.
+        findFilesInDir(dir, `**/*.${key}.js`).forEach(filepath => {
+          const replace = `.${key}.js$`;
+          const moduleId = filepath.replace(new RegExp(replace), '');
+          const absolutePath = path.join(dir, filepath);
+          moduleGroupInfo.set(moduleId, {
+            id: moduleId,
+            absolutePath,
+            relativePath: filepath,
+            getModule: () => moduleManager.get<ModuleType>(absolutePath),
+          });
+        });
+      }
+
+      return moduleGroupInfo;
+    },
+
+    reset: () => {
+      // Use config here, because outside this function, the config object is not
+      // already defined.
+      const dir = config[`${key}Dir`];
+      moduleManager.removeAll(new RegExp(`^${dir}`));
+      moduleGroupInfo.clear();
+    },
+  };
+
+  return moduleGroupManager;
+};

package/src/lib/utils/module/index.ts

@@ -0,0 +1,2 @@
+export * from './moduleManager';
+export * from './dirBasedModuleGroupManager';

package/src/lib/utils/module/module.types.ts

@@ -0,0 +1,57 @@
+/**
+ * A manager for a group of user-land modules.
+ *
+ * @typeParam ModuleType - The type of module being managed.
+ */
+export type ModuleGroupManager<ModuleType> = {
+  /**
+   * Gets an array with information of each module inside a module group.
+   *
+   * @returns An array with information of each detected module, containing:
+   * - module ID
+   * - module's absolute path
+   * - module's relative path
+   * - a function to load the module on demand
+   */
+  getModuleGroupInfo(): Map<string, ModuleInfo<ModuleType>>;
+
+  /**
+   * Resets the cache of found modules inside a module group.
+   */
+  reset(): void;
+};
+
+/**
+ * Information about a user-land module.
+ *
+ * @typeParam ModuleType - The type of the module.
+ */
+export type ModuleInfo<ModuleType> = {
+  /**
+   * Module ID.
+   *
+   * Given the following modules, their IDs are:
+   * - main.hook.js: main
+   * - dir/main.hook.js: dir/main
+   * - dir/taxonomy.hook.js: dir/taxonomy
+   * - latestContents.query.js: latestContents
+   * - dir/latestContents.query.js: dir/latestContents
+   * - dir/searchByTitle.query.js: dir/searchByTitle
+   */
+  id: string;
+
+  /**
+   * Module's absolute path.
+   */
+  absolutePath: string;
+
+  /**
+   * Module's relative path inside module group directory.
+   */
+  relativePath: string;
+
+  /**
+   * Gets a module, loading it if not already loaded.
+   */
+  getModule(): ModuleType;
+};