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

package/src/lib/config/config.ts

@@ -0,0 +1,143 @@
+import fs from 'fs';
+import path from 'path';
+import { RunMode } from '@lib/dataServer.types';
+import { hasKey } from '@lib/utils/object';
+import { ConfigOptions, NonSanitizedConfigOptions } from './config.types';
+import {
+  InvalidRunMode,
+  MissingDirectory,
+  NonWritableDirectory,
+  MissingRequiredOption,
+} from './error';
+
+const config: ConfigOptions = Object.create(null); // no inherited properties
+
+/**
+ * Configures the data server.
+ *
+ * @remarks
+ * It validates provided configuration and returns a sanitized and immutable
+ * configuration object. It throws several errors if validation is not passing.
+ *
+ * @param options - Configuration options, @see {@link ConfigOptions}
+ *
+ * @returns - The sanitized and immutable configuration object.
+ *
+ * @throws {@link MissingRequiredOption}
+ * Exception thrown if the dataDir or runMode are not provided.
+ *
+ * @throws {@link MissingDirectory}
+ * Exception thrown if any of the provided paths (dataDir, workDir,
+ * queryDir, hookDir or taskDir) is not found.
+ *
+ * @throws {@link InvalidRunMode}
+ * Exception thrown if runMode is not valid.
+ */
+const setConfig = (options: NonSanitizedConfigOptions): ConfigOptions => {
+  const localOptions = options;
+  // Check that required options are provided.
+  // Since this method is publicly accessible at runtime, it is not
+  // possible to rely on TypeScript type safety.
+  if (!localOptions.dataDir) {
+    throw new MissingRequiredOption('dataDir');
+  }
+  localOptions.dataDir = path.resolve(localOptions.dataDir);
+  if (
+    !fs.existsSync(localOptions.dataDir) ||
+    !fs.lstatSync(localOptions.dataDir).isDirectory()
+  ) {
+    throw new MissingDirectory('dataDir', localOptions.dataDir);
+  }
+  // fs.realpathSync() throws an error if path does not exist.
+  localOptions.dataDir = fs.realpathSync(localOptions.dataDir);
+
+  if (localOptions.workDir) {
+    localOptions.workDir = path.resolve(localOptions.workDir);
+    if (
+      !fs.existsSync(localOptions.workDir) ||
+      !fs.lstatSync(localOptions.workDir).isDirectory()
+    ) {
+      throw new MissingDirectory('workDir', localOptions.workDir);
+    }
+    // fs.realpathSync() throws an error if path does not exist.
+    localOptions.workDir = fs.realpathSync(localOptions.workDir);
+  }
+
+  if (localOptions.queryDir) {
+    localOptions.queryDir = path.resolve(localOptions.queryDir);
+    if (
+      !fs.existsSync(localOptions.queryDir) ||
+      !fs.lstatSync(localOptions.queryDir).isDirectory()
+    ) {
+      throw new MissingDirectory('queryDir', localOptions.queryDir);
+    }
+    // fs.realpathSync() throws an error if path does not exist.
+    localOptions.queryDir = fs.realpathSync(localOptions.queryDir);
+  }
+
+  if (localOptions.hookDir) {
+    localOptions.hookDir = path.resolve(localOptions.hookDir);
+    if (
+      !fs.existsSync(localOptions.hookDir) ||
+      !fs.lstatSync(localOptions.hookDir).isDirectory()
+    ) {
+      throw new MissingDirectory('hookDir', localOptions.hookDir);
+    }
+    // fs.realpathSync() throws an error if path does not exist.
+    localOptions.hookDir = fs.realpathSync(localOptions.hookDir);
+  }
+
+  if (localOptions.taskDir) {
+    localOptions.taskDir = path.resolve(localOptions.taskDir);
+    if (
+      !fs.existsSync(localOptions.taskDir) ||
+      !fs.lstatSync(localOptions.taskDir).isDirectory()
+    ) {
+      throw new MissingDirectory('taskDir', localOptions.taskDir);
+    }
+    // fs.realpathSync() throws an error if path does not exist.
+    localOptions.taskDir = fs.realpathSync(localOptions.taskDir);
+  }
+
+  if (localOptions.dumpDir) {
+    localOptions.dumpDir = path.resolve(localOptions.dumpDir);
+    if (
+      !fs.existsSync(localOptions.dumpDir) ||
+      !fs.lstatSync(localOptions.dumpDir).isDirectory()
+    ) {
+      throw new MissingDirectory('dumpDir', localOptions.dumpDir);
+    }
+    try {
+      fs.accessSync(localOptions.dumpDir, fs.constants.W_OK);
+    } catch (e) {
+      throw new NonWritableDirectory('dumpDir', localOptions.dumpDir);
+    }
+    // fs.realpathSync() throws an error if path does not exist.
+    localOptions.dumpDir = fs.realpathSync(localOptions.dumpDir);
+  }
+
+  if (!localOptions.runMode) {
+    localOptions.runMode = RunMode.PROD;
+  }
+  if (!Object.values(RunMode).includes(localOptions.runMode)) {
+    throw new InvalidRunMode(localOptions.runMode);
+  }
+
+  Object.keys(localOptions).forEach(key => {
+    if (hasKey(localOptions, key)) {
+      Object.defineProperty(config, key, {
+        enumerable: true,
+        configurable: false,
+        writable: false,
+        // Remove leading slash from all directories.
+        value:
+          key === 'runMode'
+            ? localOptions[key]
+            : localOptions[key]?.replace(/\/$/, ''),
+      });
+    }
+  });
+  return Object.freeze(config);
+};
+
+export { config, setConfig };

package/src/lib/config/config.types.ts

@@ -0,0 +1,87 @@
+import { RunMode } from '@lib/dataServer.types';
+
+/**
+ * Configuration options.
+ */
+export type ConfigOptions = {
+  /**
+   * Path to the directory where data is stored.
+   */
+  dataDir: string;
+
+  /**
+   * Path to the directory where work data is stored. Optional.
+   */
+  workDir?: string;
+
+  /**
+   * Path to the directory where queries are stored. Optional.
+   */
+  queryDir?: string;
+
+  /**
+   * Path to the directory where hooks are stored. Optional.
+   */
+  hookDir?: string;
+
+  /**
+   * Path to the directory where tasks are stored. Optional.
+   */
+  taskDir?: string;
+
+  /**
+   * Path to the directory where dumps are stored. Optional.
+   */
+  dumpDir?: string;
+
+  /**
+   * Run mode (dev or prod).
+   */
+  runMode: RunMode;
+};
+
+/**
+ * Non-sanitized configuration options.
+ *
+ * @remarks
+ * Options received by Data Server before validating them. They are the same as
+ * {@link ConfigOptions} but with an optional runMode.
+ *
+ * @see {@link ConfigOptions}
+ */
+export type NonSanitizedConfigOptions = {
+  /**
+   * Path to the directory where data is stored.
+   */
+  dataDir: string;
+
+  /**
+   * Path to the directory where work data is stored. Optional.
+   */
+  workDir?: string;
+
+  /**
+   * Path to the directory where queries are stored. Optional.
+   */
+  queryDir?: string;
+
+  /**
+   * Path to the directory where hooks are stored. Optional.
+   */
+  hookDir?: string;
+
+  /**
+   * Path to the directory where tasks are stored. Optional.
+   */
+  taskDir?: string;
+
+  /**
+   * Path to the directory where dumps are stored. Optional.
+   */
+  dumpDir?: string;
+
+  /**
+   * Run mode (dev or prod).
+   */
+  runMode?: RunMode;
+};

package/src/lib/config/error/InvalidRunMode.ts

@@ -0,0 +1,17 @@
+import { DomainError } from '@lib/error/DomainError';
+
+/**
+ * Defines a custom error for invalid run modes.
+ *
+ * @internal
+ */
+export class InvalidRunMode extends DomainError {
+  /**
+   * Constructs a new error for invalid run modes.
+   *
+   * @param runMode - the value of the invalid runMode.
+   */
+  constructor(runMode: string) {
+    super(`Invalid value provided for "runMode": "${runMode}"`);
+  }
+}

package/src/lib/config/error/MissingDirectory.ts

@@ -0,0 +1,30 @@
+import { DomainError } from '@lib/error/DomainError';
+
+/**
+ * Defines a custom error for missing directories.
+ *
+ * @internal
+ */
+export class MissingDirectory extends DomainError {
+  /**
+   * The configuration id of the missing directory (dataDir, queryDir, etc).
+   */
+  directoryId: string;
+
+  /**
+   * Path of the missing directory.
+   */
+  path: string;
+
+  /**
+   * Constructs a new error for missing directories.
+   *
+   * @param directoryId - the configuration id of the missing directory (dataDir, queryDir, etc).
+   * @param path - the path of the missing directory.
+   */
+  constructor(directoryId: string, path: string) {
+    super(`Cannot find "${directoryId}" directory: "${path}"`);
+    this.directoryId = directoryId;
+    this.path = path;
+  }
+}

package/src/lib/config/error/MissingRequiredOption.ts

@@ -0,0 +1,23 @@
+import { DomainError } from '@lib/error/DomainError';
+
+/**
+ * Defines a custom error for missing required options.
+ *
+ * @internal
+ */
+export class MissingRequiredOption extends DomainError {
+  /**
+   * The name of the missing required option.
+   */
+  requiredOption: string;
+
+  /**
+   * Constructs a new error for missing required options.
+   *
+   * @param requiredOption - the name of the missing required option.
+   */
+  constructor(requiredOption: string) {
+    super(`Required option not provided: "${requiredOption}".`);
+    this.requiredOption = requiredOption;
+  }
+}

package/src/lib/config/error/NonWritableDirectory.ts

@@ -0,0 +1,30 @@
+import { DomainError } from '@lib/error/DomainError';
+
+/**
+ * Defines a custom error for non-writable directories.
+ *
+ * @internal
+ */
+export class NonWritableDirectory extends DomainError {
+  /**
+   * The configuration id of the non-writable directory (dataDir, queryDir, etc).
+   */
+  directoryId: string;
+
+  /**
+   * Path of the non-writable directory.
+   */
+  path: string;
+
+  /**
+   * Constructs a new error for non-writable directories.
+   *
+   * @param directoryId - the configuration id of the non-writable directory (dataDir, queryDir, etc).
+   * @param path - the path of the non-writable directory.
+   */
+  constructor(directoryId: string, path: string) {
+    super(`Directory "${directoryId}" is not writable: "${path}"`);
+    this.directoryId = directoryId;
+    this.path = path;
+  }
+}

package/src/lib/config/error/index.ts

@@ -0,0 +1,4 @@
+export * from './InvalidRunMode';
+export * from './MissingDirectory';
+export * from './NonWritableDirectory';
+export * from './MissingRequiredOption';

package/src/lib/config/index.ts

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

package/src/lib/dataServer.ts

@@ -0,0 +1,81 @@
+import { configureLogger } from '@lib/utils/logger';
+import { LogLevel, LogFile } from '@lib/utils/logger/logger.types';
+import { initWatcher } from '@lib/watcher';
+import { setConfig } from '@lib/config';
+import { dataDirManager } from '@lib/store/dataDir';
+import { store } from '@lib/store';
+import { Store } from '@lib/store/store.types';
+import { queryRunner } from '@lib/query';
+import { taskRunner } from '@lib/task/taskRunner';
+import {
+  QueryRunner,
+  QuerySuccessfulResponse,
+  QueryErrorResponse,
+  QueryArgs,
+  QueryModule,
+  CacheStatus,
+} from '@lib/query/query.types';
+import {
+  RunMode,
+  DataServerReturn,
+  DataServerInitOptions,
+} from './dataServer.types';
+
+/**
+ * The Data Server instance.
+ *
+ * @public
+ */
+const dataServer = {
+  /**
+   * Initializes the Data Server.
+   *
+   * @param options - Configuration options
+   *
+   * @returns An object with the data store and the queryRunner service.
+   */
+  init: (options: DataServerInitOptions): DataServerReturn => {
+    // Configure logger.
+    configureLogger(options.logLevel, options.logFile);
+
+    // Configure data server.
+    const config = setConfig({
+      dataDir: options.dataDir,
+      workDir: options.workDir,
+      queryDir: options.queryDir,
+      hookDir: options.hookDir,
+      taskDir: options.taskDir,
+      dumpDir: options.dumpDir,
+      runMode: options.runMode,
+    });
+
+    // Start watcher.
+    if (config.runMode === RunMode.DEV) {
+      initWatcher();
+    }
+
+    // Load data from dataDir.
+    dataDirManager.load();
+
+    return {
+      store,
+      queryRunner,
+      taskRunner,
+    };
+  },
+};
+export {
+  dataServer,
+  DataServerInitOptions,
+  DataServerReturn,
+  RunMode,
+  LogLevel,
+  LogFile,
+  Store,
+  QueryRunner,
+  QuerySuccessfulResponse,
+  QueryErrorResponse,
+  QueryArgs,
+  QueryModule,
+  CacheStatus,
+};

package/src/lib/dataServer.types.ts

@@ -0,0 +1,98 @@
+import { LogLevel, LogFile } from '@lib/utils/logger/logger.types';
+import { QueryRunner } from '@lib/query/query.types';
+import { TaskRunner } from './task/task.types';
+import { Store } from './store/store.types';
+
+/**
+ * Init options for Data Server.
+ *
+ * @public
+ */
+export type DataServerInitOptions = {
+  /**
+   * Log level. Optional. @see {@link LogLevel}
+   */
+  logLevel?: LogLevel;
+
+  /**
+   * Path to the log file. Optional. @see {@link LogFile}
+   */
+  logFile?: LogFile;
+
+  /**
+   * Log level for the log file. Optional. @see {@link LogLevel}
+   */
+  logFileLevel?: LogLevel;
+
+  /**
+   * Path to the directory where data is stored.
+   */
+  dataDir: string;
+
+  /**
+   * Path to the directory where work data is stored. Optional.
+   */
+  workDir?: string;
+
+  /**
+   * Path to the directory where queries are stored. Optional.
+   */
+  queryDir?: string;
+
+  /**
+   * Path to the directory where hooks are stored. Optional.
+   */
+  hookDir?: string;
+
+  /**
+   * Path to the directory where tasks are stored. Optional.
+   */
+  taskDir?: string;
+
+  /**
+   * Path to the directory where dumps are stored. Optional.
+   */
+  dumpDir?: string;
+
+  /**
+   * Run mode (dev or prod).
+   */
+  runMode: RunMode;
+};
+
+/**
+ * Available run modes: dev or prod.
+ *
+ * @public
+ */
+export enum RunMode {
+  DEV = 'dev',
+  PROD = 'prod',
+}
+
+/**
+ * A helper to get RunMode type as strings. @see {@link RunMode}.
+ */
+export type RunModeStrings = keyof typeof RunMode;
+
+/**
+ * Data returned by Data Server once initialized.
+ *
+ * @public
+ */
+export type DataServerReturn = {
+  /**
+   * The data store.
+   */
+  store: Store;
+
+  /**
+   * The query runner, to be able to run queries on demand.
+   */
+  queryRunner: QueryRunner;
+
+  /**
+   * The task runner, to be able to run tasks on demand.
+   */
+  taskRunner: TaskRunner;
+};

package/src/lib/error/DomainError.ts

@@ -0,0 +1,18 @@
+/**
+ * Defines a custom error that extends the Error class.
+ *
+ * @internal
+ */
+export class DomainError extends Error {
+  constructor(message: string) {
+    super(message);
+
+    // Ensure the name of this error is the same as the class name.
+    this.name = this.constructor.name;
+
+    // This clips the constructor invocation from the stack trace.
+    // It's not absolutely essential, but it does make the stack trace a little nicer.
+    // @see https://nodejs.org/api/errors.html#errors_error_capturestacktrace_targetobject_constructoropt
+    Error.captureStackTrace(this, this.constructor);
+  }
+}

package/src/lib/index.ts

@@ -0,0 +1,4 @@
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+require('module-alias')(`${__dirname}/../..`);
+
+export * from './dataServer';

package/src/lib/query/__tests__/queryRunner.test.ts

@@ -0,0 +1,61 @@
+import fs from 'fs';
+import path from 'path';
+import { config } from '@lib/config';
+import { RunMode } from '@lib/dataServer.types';
+import { cache } from '@lib/utils/cache';
+import { logger } from '@lib/utils/logger';
+import { isQueryErrorResponse } from '../query.types';
+import { queryRunner } from '../queryRunner';
+import { queryManager } from '../queryManager';
+
+beforeEach(() => {
+  config.queryDir = fs.realpathSync(
+    path.resolve('src/__tests__/fixtures/query'),
+  );
+  config.runMode = RunMode.PROD;
+});
+
+let random = 0;
+
+describe('QueryRunner test', () => {
+  describe('getAvailableQueryIds', () => {
+    it('Returns correct queries ids from fixtures', () => {
+      expect(Array.from(queryManager.getModuleGroupInfo().keys())).toEqual([
+        'error',
+        'noHandler',
+        'query1',
+        'query2',
+      ]);
+    });
+  });
+
+  describe('run', () => {
+    it('Returns query data', () => {
+      cache.bin('query').clear();
+      const queryResponse = queryRunner.run('query1?x=x&y=33');
+      const data =
+        !isQueryErrorResponse(queryResponse) && queryResponse.data[0];
+      expect(data.id).toEqual('33');
+      ({ random } = data);
+    });
+
+    it('Returns query data from cache', () => {
+      const queryResponse = queryRunner.run('query1?x=x&y=33');
+      const response = !isQueryErrorResponse(queryResponse)
+        ? queryResponse
+        : null;
+      expect(response?.metadata?.cache).toBeTruthy();
+      expect(response?.data?.[0]?.random).toEqual(random);
+    });
+
+    it('Logs error when query fails', () => {
+      logger.error = jest.fn();
+      try {
+        queryRunner.run('error');
+      } catch (e) {
+        // none
+      }
+      expect(logger.error).toHaveBeenCalled();
+    });
+  });
+});

package/src/lib/query/index.ts

@@ -0,0 +1,2 @@
+export * from './queryManager';
+export * from './queryRunner';