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

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

@@ -0,0 +1,144 @@
+/* eslint-disable global-require */
+/* eslint-disable import/no-dynamic-require */
+import clearModule from 'clear-module';
+import { logger } from '@lib/utils/logger';
+import { config } from '@lib/config';
+import { store } from '@lib/store';
+
+/**
+ * Internal module cache.
+ *
+ * @remarks
+ * It does not use the shared cache util since this cache must to be
+ * managed only by this module, and should not be accessible nor
+ * managed from the outside.
+ */
+const internalModuleCache: Record<string, any> = {};
+
+/**
+ * Internal resolve cache.
+ *
+ * @remarks
+ * It does not use the shared cache util since this cache must be
+ * managed only by this module, and should not be accessible nor
+ * managed from the outside.
+ */
+const internalResolveCache: Record<string, any> = {};
+
+/**
+ * Resolves a path to a module
+ *
+ * @param modulePath - A path to a module
+ * @returns The resolved path, or the given unresolved path if module cannot be found
+ */
+const resolve = (modulePath: string): string => {
+  let resolvedModulePath = internalResolveCache[modulePath];
+  if (!resolvedModulePath) {
+    try {
+      resolvedModulePath = require.resolve(modulePath);
+    } catch (e) {
+      resolvedModulePath = modulePath;
+    }
+    internalResolveCache[modulePath] = resolvedModulePath;
+  }
+  return resolvedModulePath;
+};
+
+/**
+ * Module system that manages the caching of modules.
+ *
+ * @remarks
+ * Modules are cached by Node.js when they are required. This module handler
+ * is able to remove them from Node.js cache and reload them from scratch.
+ *
+ * This manager is aimed at handling "user-land" modules, i.e.- modules managed
+ * by users and not part of the Data Server core. Those "user-land" modules are
+ * queries and hooks, so trying to manage other kind of module will throw and error.
+ */
+export const moduleManager = {
+  /**
+   * Loads a module from scratch
+   *
+   * @remarks
+   * Removes a module from Node.js cache, and loads it from scratch.
+   * If the module is not valid or not found, it logs an error and throws
+   * an exception.
+   *
+   * @param modulePath - Path to the module to be loaded
+   * @typeParam Type - Type of the module to be loaded
+   *
+   * @returns - The requested module
+   *
+   * @throws
+   * An exception if the module is not valid or it cannot be loaded.
+   */
+  load: <Type>(modulePath: string): Type => {
+    const resolvedModulePath = resolve(modulePath);
+    moduleManager.remove(resolvedModulePath, { useLogger: false });
+    try {
+      internalModuleCache[resolvedModulePath] = require(resolvedModulePath);
+    } catch (e) {
+      logger.error(`Module "${resolvedModulePath}" not found.`);
+      throw e;
+    }
+    if (internalModuleCache[resolvedModulePath].onModuleLoad) {
+      internalModuleCache[resolvedModulePath].onModuleLoad({ config, store });
+    }
+    logger.debug(`Module ${resolvedModulePath} successfully loaded.`);
+    return internalModuleCache[resolvedModulePath];
+  },
+
+  /**
+   * Removes a single module from Node.js cache
+   *
+   * @param modulePath - Path to the module to be removed
+   * @param options - Object of options:
+   * useLogger: Flag to use logger or not. Useful to avoid
+   * "remove" log lines when this function is called from
+   * other functions.
+   */
+  remove: (modulePath: string, options = { useLogger: true }): void => {
+    const resolvedModulePath = resolve(modulePath);
+    clearModule(resolvedModulePath);
+    delete internalModuleCache[resolvedModulePath];
+    if (options.useLogger) {
+      logger.debug(`Module ${resolvedModulePath} successfully removed.`);
+    }
+  },
+
+  /**
+   * Removes several modules from Node.js cache at once
+   *
+   * @param regex - Regular expression to be tested again cached modules path
+   */
+  removeAll: (regex: RegExp): void => {
+    const modulePathsToBeRemoved = Object.keys(require.cache).filter(
+      modulePath => regex.test(modulePath),
+    );
+    modulePathsToBeRemoved.forEach(modulePath =>
+      moduleManager.remove(modulePath),
+    );
+  },
+
+  /**
+   * Gets a module from cache or loads it from scratch
+   *
+   * @remarks
+   * If module is not found, logs an error and throws an exception.
+   *
+   * @param modulePath - Path to the module to be loaded
+   * @typeParam Type - Type of the module to be loaded
+   *
+   * @returns - The requested module
+   *
+   * @throws
+   * An exception if the module cannot be loaded.
+   */
+  get: <Type>(modulePath: string): Type => {
+    const resolvedModulePath = resolve(modulePath);
+    return (
+      internalModuleCache[resolvedModulePath] ||
+      moduleManager.load(resolvedModulePath)
+    );
+  },
+};

package/src/lib/utils/object/__tests__/objectUtils.test.ts

@@ -0,0 +1,62 @@
+import { getObjValue } from '..';
+import { isEmptyObject, hasKey, deepClone, jsonify } from '../objectUtils';
+
+describe('Object utils test', () => {
+  describe('isEmptyObject', () => {
+    it('returns true for an empty object', () => {
+      expect(isEmptyObject({})).toBe(true);
+    });
+    it('returns false for a non empty object', () => {
+      expect(isEmptyObject({ x: 1 })).toBe(false);
+    });
+  });
+
+  describe('hasKey', () => {
+    it('returns true if an object has a given key', () => {
+      expect(hasKey({ x: 1 }, 'x')).toBe(true);
+    });
+    it('returns false if an object does not have a given key', () => {
+      expect(hasKey({ x: 1 }, 'y')).toBe(false);
+    });
+  });
+
+  describe('deepClone', () => {
+    it('returns an object equal to the given one, without references to nested objects', () => {
+      const anObject = { x: 1, y: {} };
+      const anotherObject = { z: 34 };
+      anObject.y = anotherObject;
+      const clonedObject = deepClone(anObject);
+      expect(clonedObject).toStrictEqual(anObject);
+      anotherObject.z = 22;
+      expect(clonedObject).not.toStrictEqual(anObject);
+    });
+  });
+  describe('getObjectValue', () => {
+    const testObject = { x: { y: { z: 'value' } } };
+    it('gets object value with default separator', () => {
+      expect(getObjValue(testObject, 'x.y.z')).toBe('value');
+    });
+    it('gets object value with custom separator', () => {
+      expect(getObjValue(testObject, 'x/y/z', '/')).toBe('value');
+    });
+    it('gets object value with array separator', () => {
+      expect(getObjValue(testObject, ['x', 'y', 'z'])).toBe('value');
+    });
+    it('gets undefined when path does not exist', () => {
+      expect(getObjValue(testObject, 'x.z.z')).toBeUndefined();
+    });
+  });
+
+  describe('jsonify', () => {
+    const testObject = {
+      x: new Set([1, 2]),
+      y: new Map([['mapKey', 'mapValue']]),
+    };
+    it('jsonify object containing Set and Map', () => {
+      expect(jsonify(testObject)).toEqual({
+        x: [1, 2],
+        y: { mapKey: 'mapValue' },
+      });
+    });
+  });
+});

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

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

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

@@ -0,0 +1,74 @@
+export type ObjectType = Record<string, unknown>;
+
+/**
+ * Structure where a content's data and metadata os hold.
+ *
+ * @remarks
+ * This type describes any JSON object, which can contain any data, but
+ * it is usually structured this way:
+ *
+ * @example
+ * ```
+ * {
+ *  "data": {
+ *    "content": {
+ *      ...,
+ *    }
+ *  }
+ *  "metadata": {
+ *    "includes": [
+ *	    "data.content.author.entity.entityInclude",
+ *	    "data.content.image.entity.entityInclude",
+ *	    "data.content.queryInclude"
+ *    ]
+ *  }
+ * }
+ * ```
+ */
+export type Json = {
+  [key: string]: any;
+
+  /**
+   * Optional structure for a content's data.
+   */
+  data?: {
+    [key: string]: any;
+    /**
+     * Optional object that holds the fields of a Drupal content.
+     */
+    content?: Record<string, any>;
+  };
+
+  /**
+   * Optional structure for metadata includes.
+   */
+  metadata?: {
+    [key: string]: any;
+    /**
+     * Optional array for metadata includes.
+     *
+     * @remarks
+     * Every include path is stored in this array, so they can be
+     * easily accessed.
+     *
+     * @example
+     * ```
+     * "metadata": {
+     *  "includes": [
+     *    "static": [
+     *	    "data.content.author.entity.entityInclude",
+     *	    "data.content.image.entity.entityInclude",
+     *    ]
+     *    "dynamic": [
+     *	    "data.content.queryInclude"
+     *    ]
+     *  ]
+     * }
+     * ```
+     */
+    includes?: {
+      static?: Record<string, string>;
+      dynamic?: Record<string, string>;
+    };
+  };
+};

package/src/lib/utils/object/objectUtils.ts

@@ -0,0 +1,71 @@
+import { ObjectType } from './object.types';
+
+/**
+ * Checks if an object is empty (i.e.- contains zero keys)
+ *
+ * @param object - An object
+ *
+ * @returns True if the object contains zero keys, false otherwise.
+ */
+export const isEmptyObject = (object: ObjectType): boolean =>
+  Object.keys(object).length === 0;
+
+/**
+ * Checks if an object contains a key
+ *
+ * @param object - An object
+ * @param key - The name of a key
+ *
+ * @returns True if the object has the given key, false otherwise.
+ */
+export const hasKey = <O>(object: O, key: PropertyKey): key is keyof O => {
+  return key in object;
+};
+
+/**
+ * Clones an object and all its nested objects
+ *
+ * @param object - An object to be cloned
+ *
+ * @returns An identical object without references to nested objects
+ */
+export const deepClone = (object: ObjectType): ObjectType =>
+  JSON.parse(JSON.stringify(object));
+
+/**
+ * Gets object property by property path
+ *
+ * @param object - An object
+ * @param path - A string or array of strings
+ * @param separator - Optional separator if path is a string. '.' by default.
+ *
+ * @returns Value of the path or undefined
+ */
+export const getObjValue = (
+  object: ObjectType,
+  path: string | string[],
+  separator?: string,
+): any | undefined => {
+  const pathArray = Array.isArray(path) ? path : path.split(separator || '.');
+  return pathArray.reduce(
+    (previous: any, current: any) => previous?.[current],
+    object,
+  );
+};
+
+/**
+ * Converts a JavaScript value containing Set and Map, to a JSON object.
+ *
+ * @param value - A JavaScript value to be converted.
+ *
+ * @returns A JSON object
+ */
+export const jsonify = <T>(value: T): T => {
+  return JSON.parse(
+    JSON.stringify(value, (k, v) => {
+      if (v instanceof Set) return [...v];
+      if (v instanceof Map) return Object.fromEntries(v);
+      return v;
+    }),
+  );
+};

package/src/lib/utils/string/__tests__/stringUtils.test.ts

@@ -0,0 +1,30 @@
+import { logger } from '@lib/utils/logger';
+import { parseJsonString, parseURLSearchParams } from '../stringUtils';
+
+describe('String utils test', () => {
+  describe('parseJsonString', () => {
+    logger.error = jest.fn();
+    it('parses a well-formed JSON string without logging any error', () => {
+      expect(parseJsonString('{"key": "value"}')).not.toBeNull();
+      expect(logger.error).not.toHaveBeenCalled();
+    });
+    it('logs an error when parsing a malformed JSON string', () => {
+      expect(parseJsonString('malformed-json-string')).toBeNull();
+      expect(logger.error).toHaveBeenCalled();
+    });
+  });
+
+  describe('parseURLSearchParams', () => {
+    it('parses a query string with non repeated keys and returns an object', () => {
+      const parsedQuery = parseURLSearchParams('arg1=a&arg2=b');
+      const expectedValue = { arg1: 'a', arg2: 'b' };
+      expect(parsedQuery).toStrictEqual(expectedValue);
+    });
+
+    it('parses a query string with repeated keys and returns an object', () => {
+      const parsedQuery = parseURLSearchParams('arg1=a&arg2=b&arg1=c');
+      const expectedValue = { arg1: ['a', 'c'], arg2: 'b' };
+      expect(parsedQuery).toEqual(expectedValue);
+    });
+  });
+});

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

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

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

@@ -0,0 +1 @@
+export type URLSearchParamsObject = Record<string, string | string[] | null>;

package/src/lib/utils/string/stringUtils.ts

@@ -0,0 +1,61 @@
+import { logger } from '@lib/utils/logger';
+import { URLSearchParamsObject } from './string.types';
+
+/**
+ * Separator for variant data files saved to storage.
+ *
+ * @remarks
+ * Refers to the separator that is used by variant data files when they are
+ * saved. If a "master" data file name is "12345.json", and its variant keys
+ * are "card" and "search", its resulting variant file names are:
+ *   - 12345--card.json
+ *   - 12345--search.json
+ * @see ExporterPluginInterface::VARIANT_SEPARATOR in https://www.drupal.org/project/static_suite
+ *
+ * @sealed
+ * Not intended to be over ride.
+ */
+export const VARIANT_SEPARATOR = '--';
+
+/**
+ * Parses a JSON string and logs an error on failure.
+ *
+ * @param jsonString - The string to be parsed.
+ *
+ * @returns A JSON object or null on error.
+ */
+export const parseJsonString = (jsonString: string): any => {
+  let json = null;
+  try {
+    json = JSON.parse(jsonString);
+  } catch (error) {
+    logger.error(`Error parsing JSON data "${jsonString}": ${error}`);
+  }
+  return json;
+};
+
+/**
+ * Parses a raw URL search (aka "query string") into an object.
+ *
+ * @remarks
+ * Turns a string like "arg1=a&arg2=b" into an object like
+ * \{ arg1: 'a', arg2: 'b'\}
+ *
+ * @param queryString - A raw URL search string
+ *
+ * @returns An object where its keys are the query arguments.
+ */
+export const parseURLSearchParams = (
+  queryString: string,
+): URLSearchParamsObject => {
+  const params = new URLSearchParams(queryString);
+  const obj: URLSearchParamsObject = {};
+  Array.from(params.keys()).forEach(key => {
+    if (params.getAll(key).length > 1) {
+      obj[key] = params.getAll(key);
+    } else {
+      obj[key] = params.get(key);
+    }
+  });
+  return obj;
+};

package/src/lib/watcher/index.ts

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

package/src/lib/watcher/watcher.ts

@@ -0,0 +1,66 @@
+import { config } from '@lib/config';
+import { dataDirManager } from '@lib/store/dataDir/dataDirManager';
+import { logger } from '@lib/utils/logger';
+import { cache } from '@lib/utils/cache';
+import { watch } from '@lib/utils/fs';
+import { hookManager } from '@lib/store/hook';
+import { queryManager } from '@lib/query';
+import { taskManager } from '@lib/task';
+
+/**
+ * Initializes a watcher on any file inside queryDir, hookDir and taskDir.
+ *
+ * @remarks
+ * If runMode is DEV and queryDir, hookDir and/or taskDir are defined by current
+ * configuration, a watcher is initialized on them.
+ *
+ * When something changes inside query directory:
+ * 1) Remove all modules inside the query directory, so they are required again.
+ * 2) Clear the query cache, since that is not done by the queryManager.
+ *
+ * When something changes inside hook directory:
+ * 1) Remove all modules inside the hook directory, so they are required again.
+ * 2) Reload the whole data directory so hooks can be reapplied (this implies clearing the query cache).
+ */
+export const initWatcher = (): void => {
+  const paths: string[] = [];
+  if (config.queryDir) {
+    paths.push(config.queryDir);
+  }
+  if (config.hookDir) {
+    paths.push(config.hookDir);
+  }
+  if (config.taskDir) {
+    paths.push(config.taskDir);
+  }
+
+  const listener = (filePath: string) => {
+    // Remove all modules inside the query directory.
+    if (config.queryDir && filePath.startsWith(config.queryDir)) {
+      queryManager.reset();
+      // Clear all queries, since they are stale.
+      // No need to clear the store subset cache, since no
+      // file has been added/updated/deleted.
+      cache.bin('query').clear();
+    }
+
+    // Remove all modules inside the hook directory and reload the whole
+    // data directory so hooks can be reapplied.
+    if (config.hookDir && filePath.startsWith(config.hookDir)) {
+      hookManager.reset();
+      dataDirManager.load();
+      logger.debug('Re-building store done');
+    }
+
+    // Remove all modules inside the task directory.
+    if (config.taskDir && filePath.startsWith(config.taskDir)) {
+      taskManager.reset();
+    }
+  };
+
+  watch(paths, {
+    add: listener,
+    change: listener,
+    unlink: listener,
+  });
+};

package/tsconfig.json

@@ -0,0 +1,83 @@
+{
+  "compilerOptions": {
+    /* Visit https://aka.ms/tsconfig.json to read more about this file */
+
+    /* Basic Options */
+    // "incremental": true,                         /* Enable incremental compilation */
+    "target": "ES2020" /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', 'ES2021', or 'ESNEXT'. */,
+    "module": "commonjs" /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'. */,
+    "lib": [
+      "ES2020",
+      "dom",
+      "dom.iterable"
+    ] /* Specify library files to be included in the compilation. */,
+    // "allowJs": true,                             /* Allow javascript files to be compiled. */
+    // "checkJs": true,                             /* Report errors in .js files. */
+    // "jsx": "preserve",                           /* Specify JSX code generation: 'preserve', 'react-native', 'react', 'react-jsx' or 'react-jsxdev'. */
+    "declaration": true /* Generates corresponding '.d.ts' file. */,
+    "declarationMap": true /* Generates a sourcemap for each corresponding '.d.ts' file. */,
+    // "sourceMap": true,                           /* Generates corresponding '.map' file. */
+    // "outFile": "./",                             /* Concatenate and emit output to single file. */
+    "outDir": "./dist" /* Redirect output structure to the directory. */,
+    "rootDir": "./src" /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */,
+    // "composite": true,                           /* Enable project compilation */
+    // "tsBuildInfoFile": "./",                     /* Specify file to store incremental compilation information */
+    // "removeComments": true,                      /* Do not emit comments to output. */
+    // "noEmit": true,                              /* Do not emit outputs. */
+    // "importHelpers": true,                       /* Import emit helpers from 'tslib'. */
+    "downlevelIteration": true /* Provide full support for iterables in 'for-of', spread, and destructuring when targeting 'ES5' or 'ES3'. */,
+    // "isolatedModules": true,                     /* Transpile each file as a separate module (similar to 'ts.transpileModule'). */
+
+    /* Strict Type-Checking Options */
+    "strict": true /* Enable all strict type-checking options. */,
+    // "noImplicitAny": true,                       /* Raise error on expressions and declarations with an implied 'any' type. */
+    // "strictNullChecks": true,                    /* Enable strict null checks. */
+    // "strictFunctionTypes": true,                 /* Enable strict checking of function types. */
+    // "strictBindCallApply": true,                 /* Enable strict 'bind', 'call', and 'apply' methods on functions. */
+    // "strictPropertyInitialization": true,        /* Enable strict checking of property initialization in classes. */
+    // "noImplicitThis": true,                      /* Raise error on 'this' expressions with an implied 'any' type. */
+    // "alwaysStrict": true,                        /* Parse in strict mode and emit "use strict" for each source file. */
+
+    /* Additional Checks */
+    // "noUnusedLocals": true,                      /* Report errors on unused locals. */
+    // "noUnusedParameters": true,                  /* Report errors on unused parameters. */
+    // "noImplicitReturns": true,                   /* Report error when not all code paths in function return a value. */
+    // "noFallthroughCasesInSwitch": true,          /* Report errors for fallthrough cases in switch statement. */
+    // "noUncheckedIndexedAccess": true,            /* Include 'undefined' in index signature results */
+    // "noImplicitOverride": true,                  /* Ensure overriding members in derived classes are marked with an 'override' modifier. */
+    // "noPropertyAccessFromIndexSignature": true,  /* Require undeclared properties from index signatures to use element accesses. */
+
+    /* Module Resolution Options */
+    // "moduleResolution": "node",                  /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */
+    "baseUrl": "./src" /* Base directory to resolve non-absolute module names. */,
+    "paths": {
+      "@bin/*": ["bin/*"],
+      "@http/*": ["http/*"],
+      "@lib/*": ["lib/*"],
+      "@__tests__/*": ["__tests__/*"]
+    } /* A series of entries which re-map imports to lookup locations relative to the 'baseUrl'. */,
+    // "rootDirs": [],                              /* List of root folders whose combined content represents the structure of the project at runtime. */
+    // "typeRoots": [],                             /* List of folders to include type definitions from. */
+    // "types": [],                                 /* Type declaration files to be included in compilation. */
+    // "allowSyntheticDefaultImports": true,        /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */
+    "esModuleInterop": true /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */,
+    // "preserveSymlinks": true,                    /* Do not resolve the real path of symlinks. */
+    // "allowUmdGlobalAccess": true,                /* Allow accessing UMD globals from modules. */
+
+    /* Source Map Options */
+    // "sourceRoot": "",                            /* Specify the location where debugger should locate TypeScript files instead of source locations. */
+    // "mapRoot": "",                               /* Specify the location where debugger should locate map files instead of generated locations. */
+    // "inlineSourceMap": true,                     /* Emit a single file with source maps instead of having a separate file. */
+    // "inlineSources": true,                       /* Emit the source alongside the sourcemaps within a single file; requires '--inlineSourceMap' or '--sourceMap' to be set. */
+
+    /* Experimental Options */
+    // "experimentalDecorators": true,              /* Enables experimental support for ES7 decorators. */
+    // "emitDecoratorMetadata": true,               /* Enables experimental support for emitting type metadata for decorators. */
+
+    /* Advanced Options */
+    "skipLibCheck": true /* Skip type checking of declaration files. */,
+    "forceConsistentCasingInFileNames": true /* Disallow inconsistently-cased references to the same file. */
+  },
+  "include": ["src"]
+  // "exclude": ["mocks", "**/__tests__/*", "**/*.test.ts"]
+}