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

package/src/lib/store/workDir/workDirHelper.ts

@@ -0,0 +1,59 @@
+import { getModificationDate } from '@lib/utils/fs';
+import { logger } from '@lib/utils/logger';
+import { ChangedFiles, LogLineData } from './workDir.types';
+import {
+  getLogFile,
+  getChangedLinesSince,
+  getDataFromLogLine,
+} from './storage';
+
+export const workDirHelper = {
+  /**
+   * Gets date of last modification of work directory.
+   *
+   * @returns The date of last modification of work directory, or null if directory not found.
+   */
+  getModificationDate: (): Date | null => {
+    const logFile = getLogFile();
+    return logFile ? getModificationDate(logFile) : null;
+  },
+
+  /**
+   * Get changed files since a date.
+   *
+   * @param sinceDate - Date to search
+   *
+   * @returns Object with two properties:
+   * - updated: array of changed files.
+   * - deleted: array of deleted files.
+   */
+  getChangedFilesSince: (sinceDate: Date): ChangedFiles => {
+    const changedLines = getChangedLinesSince(sinceDate);
+    const lineData: Record<string, LogLineData> = {};
+    changedLines.forEach(line => {
+      const dataFromLogLine = getDataFromLogLine(line);
+      if (dataFromLogLine) {
+        // Save lines keyed by its relativePath so only the last
+        // operation on the same file is processed.
+        lineData[dataFromLogLine.file.relativePath] = dataFromLogLine;
+      }
+    });
+    const lineDataArray: LogLineData[] = Object.values(lineData);
+
+    const updated = lineDataArray
+      .filter(data => data.operation === 'write')
+      .map(data => data.file.relativePath);
+    updated.forEach(file => {
+      logger.debug(`Found updated file "${file}"`);
+    });
+
+    const deleted = lineDataArray
+      .filter(data => data.operation === 'delete')
+      .map(data => data.file.relativePath);
+    deleted.forEach(file => {
+      logger.debug(`Found deleted file "${file}"`);
+    });
+
+    return { updated, deleted };
+  },
+};

package/src/lib/task/__tests__/taskRunner.test.ts

@@ -0,0 +1,47 @@
+import fs from 'fs';
+import path from 'path';
+import { config } from '@lib/config';
+import { RunMode } from '@lib/dataServer.types';
+import { logger } from '@lib/utils/logger';
+import { isTaskErrorResponse } from '../task.types';
+import { taskRunner } from '../taskRunner';
+import { taskManager } from '../taskManager';
+
+beforeEach(() => {
+  config.taskDir = fs.realpathSync(path.resolve('src/__tests__/fixtures/task'));
+  config.runMode = RunMode.PROD;
+});
+
+describe('TaskRunner test', () => {
+  describe('getAvailableTaskIds', () => {
+    it('Returns correct tasks ids from fixtures', () => {
+      expect(Array.from(taskManager.getModuleGroupInfo().keys())).toEqual([
+        'error',
+        'noHandler',
+        'task1',
+        'task2',
+      ]);
+    });
+  });
+
+  describe('run', () => {
+    it('Returns task data', () => {
+      const taskResponse = taskRunner.run('task1', {
+        x: 'x',
+        y: '33',
+      });
+      const data = !isTaskErrorResponse(taskResponse) && taskResponse.data[0];
+      expect(data.id).toEqual('33');
+    });
+
+    it('Logs error when task fails', () => {
+      logger.error = jest.fn();
+      try {
+        taskRunner.run('error', {});
+      } catch (e) {
+        // none
+      }
+      expect(logger.error).toHaveBeenCalled();
+    });
+  });
+});

package/src/lib/task/index.ts

@@ -0,0 +1,2 @@
+export * from './taskManager';
+export * from './taskRunner';

package/src/lib/task/task.types.ts

@@ -0,0 +1,151 @@
+import { Store } from '@lib/store/store.types';
+
+/**
+ * A service to handle the execution of tasks.
+ *
+ * @public
+ */
+export type TaskRunner = {
+  /**
+   * Runs a task and returns its results with metadata.
+   *
+   * @remarks
+   * It checks several validations before a task is run, and then task is executed.
+   *
+   * It logs an error and throws an exception if any problem occurs during the
+   * task execution.
+   *
+   * @param taskId - Task ID (filename without extension and suffix) of the task
+   * to be executed. @see {@link ModuleInfo#id | Definition of a module ID}
+   * @param args - Optional object with task arguments.
+   *
+   * @returns The result of the task as a JSON object with data and metadata keys,
+   * or an error response if some validation is not met.
+   *
+   * @example
+   * Here's a result example:
+   * ```
+   * {
+   * data: ['title 1', 'title 2'],
+   *  metadata: {
+   *    contentType: 'application/json',
+   *    execTime: 2,
+   *  }
+   * }
+   * ```
+
+  * @throws
+   * Exception thrown if any problem occurs during the task execution.
+   */
+  run(
+    taskId: string,
+    args: TaskArgs,
+  ): TaskSuccessfulResponse | TaskErrorResponse;
+};
+
+/**
+ * An object with task arguments.
+ *
+ * @public
+ */
+export type TaskArgs = Record<string, any>;
+
+/**
+ * The result that a task returns after being executed.
+ */
+export type TaskModuleResult = {
+  /**
+   * A result, which can be of any kind (and array, an object, a string, etc)
+   */
+  result: any;
+
+  /**
+   * Optional content type for the data available in "result"
+   *
+   * @remarks
+   * Data coming from the task can be anything (XML, a string, etc).
+   * This content type is added to the metadata section of the TaskResponse.
+   * @see {@link TaskSuccessfulResponse#metadata}.
+   *
+   * @defaultValue 'application/json'
+   */
+  contentType?: string;
+};
+
+/**
+ * A successful response returned after executing a task.
+ *
+ * @remarks
+ * It takes the results from a TaskModule#taskHandler, and wraps them into an
+ * structure with metadata. @see {@link TaskModule#default}
+ *
+ * @public
+ */
+export type TaskSuccessfulResponse = {
+  /**
+   * Data returned by the task. @see {@link TaskModule#default}
+   */
+  data: any;
+
+  /**
+   * Task metadata
+   */
+  metadata: {
+    /**
+     * Content type for the data available in "data"
+     *
+     * @remarks
+     * Even thought this structure is a JSON object, data coming from the
+     * task can be anything (XML, a string, etc). It must be specified so any
+     * consumer of this data knows what is being returned.
+     */
+    contentType: string;
+
+    /**
+     * Execution time taken by the task, in milliseconds.
+     */
+    execTimeMs: number;
+  };
+};
+
+/**
+ * A module that defines a task.
+ */
+export type TaskModule = {
+  /**
+   * The handler that executes a task.
+   *
+   * @remarks
+   * It receives the store data and a set of arguments, executes the task
+   * and returns its results.
+   *
+   * @param options - An object with options for the task: store and args
+   */
+  default(options: { store: Store; args: TaskArgs }): TaskModuleResult;
+};
+/**
+ * An error response returned after executing a task.
+ *
+ * @remarks
+ * It takes an string from TaskModule#taskHandler, and wraps them into an
+ * structure with metadata. @see {@link TaskModule#default}
+ *
+ * @public
+ */
+export type TaskErrorResponse = {
+  /**
+   * Error message from the task, usually coming from a failed validation.
+   */
+  error: string;
+};
+
+/**
+ * Tells whether a task response is erroneous or not.
+ *
+ * @param taskResponse - A response (successful or erroneous) from the task handler.
+ * @returns True if taskResponse is erroneous.
+ */
+export const isTaskErrorResponse = (
+  taskResponse: TaskSuccessfulResponse | TaskErrorResponse,
+): taskResponse is TaskErrorResponse =>
+  (taskResponse as TaskErrorResponse).error !== undefined;

package/src/lib/task/taskManager.ts

@@ -0,0 +1,11 @@
+import { dirBasedModuleGroupManager } from '@lib/utils/module';
+import { TaskModule } from './task.types';
+
+/**
+ * A manager for tasks stored in a user-land directory defined by configuration.
+ *
+ * @remarks
+ * It extends dirBasedModuleGroupManager, which manages groups of modules based
+ * on a directory: @see {@link dirBasedModuleGroupManager}
+ */
+export const taskManager = dirBasedModuleGroupManager<TaskModule>('task');

package/src/lib/task/taskRunner.ts

@@ -0,0 +1,79 @@
+import microtime from 'microtime';
+import { config } from '@lib/config';
+import { store } from '@lib/store';
+import { logger } from '@lib/utils/logger';
+import { taskManager } from './taskManager';
+import {
+  TaskRunner,
+  TaskErrorResponse,
+  TaskSuccessfulResponse,
+  TaskModuleResult,
+} from './task.types';
+
+let count = 0;
+
+/**
+ * Creates a TaskErrorResponse object ready to be returned to clients.
+ *
+ * @param message - Error message
+ *
+ * @returns A JSON object with an error key
+ *
+ * @internal
+ */
+const createErrorResponse = (message: string): TaskErrorResponse => {
+  logger.error(message);
+  return { error: message };
+};
+
+export const taskRunner: TaskRunner = {
+  run: (taskId, args): TaskSuccessfulResponse | TaskErrorResponse => {
+    if (!config.taskDir) {
+      return createErrorResponse('No task directory ("taskDir") configured');
+    }
+    if (!taskId) {
+      return createErrorResponse('No task ID received');
+    }
+    const taskModuleInfo = taskManager.getModuleGroupInfo().get(taskId);
+    if (!taskModuleInfo) {
+      return createErrorResponse(`Task module for ID ${taskId} not found`);
+    }
+
+    count += 1;
+    const startDate = microtime.now();
+    const argsString = JSON.stringify(args);
+    logger.debug(`#${count} Task started: "${taskId}", args "${argsString}"`);
+    const taskResult: TaskModuleResult = {
+      result: undefined,
+      contentType: undefined,
+    };
+    try {
+      const taskModule = taskModuleInfo.getModule();
+      const taskResponse = taskModule.default({
+        store,
+        args,
+      });
+      taskResult.result = taskResponse?.result;
+
+      taskResult.contentType = taskResponse?.contentType || 'application/json';
+    } catch (e) {
+      // Log error and rethrow.
+      logger.error(
+        `#${count} Task error: "${taskId}", args "${argsString}": ${e}`,
+      );
+      throw e;
+    }
+    const execTimeMs = (microtime.now() - startDate) / 1000;
+    const response: TaskSuccessfulResponse = {
+      data: taskResult.result,
+      metadata: {
+        contentType: taskResult.contentType || 'application/json',
+        execTimeMs,
+      },
+    };
+
+    logger.debug(`#${count} Task "${taskId}" took ${execTimeMs} ms.`);
+
+    return response;
+  },
+};

package/src/lib/utils/array/__tests__/arrayUtils.test.ts

@@ -0,0 +1,16 @@
+import { arrayRemoveByValue } from '../arrayUtils';
+
+describe('Array utils test', () => {
+  describe('arrayRemoveByValue', () => {
+    it('removes an existing array item by value', () => {
+      const arr = [1, 2, 3];
+      arrayRemoveByValue(arr, 2);
+      expect(arr).toEqual([1, 3]);
+    });
+    it('leaves untouched an array when removing a non existing array item by value', () => {
+      const arr = [1, 2, 3];
+      arrayRemoveByValue(arr, 4);
+      expect(arr).toEqual([1, 2, 3]);
+    });
+  });
+});

package/src/lib/utils/array/arrayUtils.ts

@@ -0,0 +1,7 @@
+// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+export const arrayRemoveByValue = (arr: any[], value: any): void => {
+  const index = arr.indexOf(value);
+  if (index !== -1) {
+    arr.splice(index, 1);
+  }
+};

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

@@ -0,0 +1,24 @@
+import { cache } from '../cacheBinManager';
+
+describe('Cache test', () => {
+  it('newly created cache bins are empty', () => {
+    expect(cache.bin('bin1').size).toBe(0);
+  });
+
+  it('using several cache bins does not affect any of them', () => {
+    cache.bin('bin1').set('key1', 'value1');
+    cache.bin('bin2').set('key2', 'value2');
+
+    expect(cache.bin('bin1').get('key1')).toBe('value1');
+    expect(cache.bin('bin2').get('key2')).toBe('value2');
+    expect(cache.bin('bin1').size).toBe(1);
+    expect(cache.bin('bin2').size).toBe(1);
+  });
+
+  it('gets the keys of all cache bins', () => {
+    cache.bin('bin1');
+    cache.bin('bin2');
+
+    expect(cache.keys()).toEqual(['bin1', 'bin2']);
+  });
+});

package/src/lib/utils/cache/cacheBinManager.ts

@@ -0,0 +1,88 @@
+export type CacheBin<Type> = Map<string, Type>;
+
+export type Cache = {
+  /**
+   * Gets a cache bin by its id.
+   *
+   * @param binId - The id of the bin.
+   * @returns The cache bin.
+   */
+  bin<Type>(binId: string): CacheBin<Type>;
+
+  /**
+   * Returns a boolean indicating whether a cache bin
+   * with the specified key exists or not.
+   *
+   * @param binId - The id of the bin.
+   * @returns True if the cache bin exists, false otherwise.
+   */
+  has(binId: string): boolean;
+
+  /**
+   * Gets an array of keys of all available cache bins.
+   *
+   * @returns An array of cache bin keys.
+   */
+  keys(): string[];
+
+  /**
+   * Clears all available cache bins.
+   */
+  clear(): void;
+};
+
+const data = new Map<string, CacheBin<any>>();
+
+/**
+ * Initializes a cache bin.
+ *
+ * @remarks
+ * If a cache bin already exists, it clears it, creating a new one.
+ * If the cache bin doesn't exist, it simply creates it.
+ *
+ * @param binId - The id of the bin.
+ * @returns The initialized cache bin.
+ *
+ */
+const initBin = <Type>(binId: string): CacheBin<Type> => {
+  data.set(binId, new Map<string, Type>());
+  return data.get(binId) as CacheBin<Type>;
+};
+
+/**
+ * Cache system based on specialized bins.
+ *
+ * All cache items belong to a specific bin ("file", "query", etc),
+ * which is a kind of "folder" or "directory" where data belonging
+ * to the same context/domain is stored altogether.
+ */
+export const cache: Cache = {
+  bin: <Type>(binId: string): CacheBin<Type> => {
+    return (data.get(binId) as CacheBin<Type>) || initBin<Type>(binId);
+  },
+
+  /**
+   * Returns a boolean indicating whether a cache bin
+   * with the specified key exists or not.
+   *
+   * @param binId - The id of the bin.
+   * @returns True if the cache bin exists, false otherwise.
+   */
+  has: binId => data.has(binId),
+
+  /**
+   * Gets an array of keys of all available cache bins.
+   *
+   * @returns An array of cache bin keys.
+   */
+  keys: () => Array.from(data.keys()),
+
+  /**
+   * Gets an array of keys of all available cache bins.
+   *
+   * @returns An array of cache bin keys.
+   */
+  clear: () => {
+    data.clear();
+  },
+};

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

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

package/src/lib/utils/fs/__tests__/fixtures/file.json

@@ -0,0 +1,3 @@
+{
+  "key": "value"
+}

package/src/lib/utils/fs/__tests__/fixtures/file.txt

@@ -0,0 +1,3 @@
+{
+  "key": "value"
+}

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

@@ -0,0 +1,93 @@
+import fs from 'fs';
+import path from 'path';
+import { logger } from '@lib/utils/logger';
+import {
+  readFile,
+  getFileContent,
+  findFilesInDir,
+  getModificationDate,
+  isJsonFile,
+} from '../fsUtils';
+
+const fixturesDir = path.join(__dirname, './fixtures/');
+const jsonFixturePath = path.join(fixturesDir, 'file.json');
+const jsonRawValue = fs.readFileSync(jsonFixturePath, 'utf8');
+const jsonParsedValue = JSON.parse(jsonRawValue);
+
+beforeEach(() => {
+  logger.error = jest.fn();
+});
+
+describe('File System utils test', () => {
+  describe('isJsonFile', () => {
+    it('detects a valid JSON filepath', () => {
+      expect(isJsonFile('valid-file.json')).toBe(true);
+    });
+    it('detects an invalid JSON filepath', () => {
+      expect(isJsonFile('invalid-file.txt')).toBe(false);
+    });
+  });
+
+  describe('readFile', () => {
+    it('reads an existing filepath without logging any error', () => {
+      expect(readFile(jsonFixturePath)).toBe(jsonRawValue);
+      expect(logger.error).not.toHaveBeenCalled();
+    });
+    it('logs an error when reading a non-existing filepath', () => {
+      expect(readFile('invalid-path')).toBeNull();
+      expect(logger.error).toHaveBeenCalled();
+    });
+  });
+
+  describe('getFileContent', () => {
+    describe('when a file exists', () => {
+      describe('if it is a JSON file', () => {
+        it('returns an object with non-null "raw" and "json" properties ', () => {
+          const fileContent = getFileContent(jsonFixturePath);
+          expect(fileContent.json).toStrictEqual(jsonParsedValue);
+          expect(fileContent.raw).toBe(jsonRawValue);
+        });
+      });
+      describe('if it is not a JSON file', () => {
+        it('returns an object with a non-null "raw" property and a null "json" property', () => {
+          const txtFixturePath = path.join(fixturesDir, 'file.txt');
+          const txtRawValue = fs.readFileSync(txtFixturePath, 'utf8');
+
+          const fileContent = getFileContent(txtFixturePath);
+
+          expect(fileContent.json).toBeNull();
+          expect(fileContent.raw).toBe(txtRawValue);
+        });
+      });
+    });
+    describe('when a file does not exist', () => {
+      it('returns an object with null "raw" and "json" properties', () => {
+        const fileContent = getFileContent('invalid-path');
+        expect(fileContent.json).toBeNull();
+        expect(fileContent.raw).toBeNull();
+      });
+    });
+  });
+
+  describe('findFilesInDir', () => {
+    it('finds a file non-recursively in a directory', () => {
+      const filesInDir = findFilesInDir(fixturesDir, '*.txt');
+      expect(filesInDir).toStrictEqual(['file.txt']);
+    });
+    it('finds several files recursively in a directory', () => {
+      const filesInDir = findFilesInDir(fixturesDir);
+      expect(filesInDir).toStrictEqual(['file.json', 'file.txt']);
+    });
+  });
+
+  describe('getModificationDate', () => {
+    it('returns a Date for an existing filepath without logging any error', () => {
+      expect(getModificationDate(jsonFixturePath) instanceof Date).toBe(true);
+      expect(logger.error).not.toHaveBeenCalled();
+    });
+    it('returns null and logs an error for a non-existing filepath', () => {
+      expect(getModificationDate('invalid-path')).toBeNull();
+      expect(logger.error).toHaveBeenCalled();
+    });
+  });
+});

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

@@ -0,0 +1,21 @@
+import { Json } from '@lib/utils/object/object.types';
+
+/**
+ * An object that represents a file's contents.
+ *
+ * @remarks
+ * 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 type FileType = {
+  /**
+   * The raw contents of the file, as a string. Null if file is not found.
+   */
+  raw: string | null;
+
+  /**
+   * The file contents parsed as JSON, if file is a JSON file. Null if not a JSON file.
+   */
+  json: Json | null;
+};