@eventvisor/core 0.0.2

package/src/cli/cli.ts

@@ -0,0 +1,110 @@
+import type { ProjectConfig } from "../config";
+import { Datasource } from "../datasource";
+
+import { commonPlugins, nonProjectPlugins, projectBasedPlugins } from "./plugins";
+
+export interface ParsedOptions {
+  _: string[];
+  [key: string]: any;
+}
+
+export interface PluginHandlerOptions {
+  rootDirectoryPath: string;
+  projectConfig: ProjectConfig;
+  datasource: Datasource;
+  parsed: ParsedOptions;
+}
+
+export interface Plugin {
+  command: string; // single word
+  handler: (options: PluginHandlerOptions) => Promise<void | boolean>;
+  examples: {
+    command: string; // full command usage
+    description: string;
+  }[];
+}
+
+export interface RunnerOptions {
+  rootDirectoryPath: string;
+
+  // optional because CLI can be used without a project
+  projectConfig?: ProjectConfig;
+  datasource?: Datasource;
+}
+
+export async function runCLI(runnerOptions: RunnerOptions) {
+  const yargs = require("yargs");
+
+  let y = yargs(process.argv.slice(2)).usage("Usage: <command> [options]");
+  const registeredSubcommands: string[] = [];
+
+  const { rootDirectoryPath, projectConfig, datasource } = runnerOptions;
+
+  function registerPlugin(plugin: Plugin) {
+    const subcommand = plugin.command.split(" ")[0];
+
+    if (registeredSubcommands.includes(subcommand)) {
+      console.warn(`Plugin "${subcommand}" already registered. Skipping.`);
+      return;
+    }
+
+    y = y.command({
+      command: plugin.command,
+      handler: async function (parsed: ParsedOptions) {
+        // @NOTE: in future, allow yargs options to be defined via plugins
+        if (parsed.schemaVersion && typeof parsed.schemaVersion !== "string") {
+          parsed.schemaVersion = parsed.schemaVersion.toString();
+        }
+
+        try {
+          const result = await plugin.handler({
+            rootDirectoryPath,
+            projectConfig,
+            datasource,
+            parsed,
+          } as PluginHandlerOptions);
+
+          if (result === false) {
+            process.exit(1);
+          }
+        } catch (error) {
+          console.error(error);
+          process.exit(1);
+        }
+      },
+    });
+
+    for (const example of plugin.examples) {
+      y = y.example(`$0 ${example.command}`, example.description);
+    }
+
+    registeredSubcommands.push(subcommand);
+  }
+
+  // non project-based plugins
+  if (!projectConfig) {
+    for (const plugin of nonProjectPlugins) {
+      registerPlugin(plugin);
+    }
+  }
+
+  // project-based plugins
+  if (projectConfig) {
+    for (const plugin of [...projectBasedPlugins, ...(projectConfig.plugins || [])]) {
+      registerPlugin(plugin);
+    }
+  }
+
+  // common plugins
+  for (const plugin of commonPlugins) {
+    registerPlugin(plugin);
+  }
+
+  // show help if no command is provided
+  y.command({
+    command: "*",
+    handler() {
+      y.showHelp();
+    },
+  }).argv;
+}

package/src/cli/index.ts

@@ -0,0 +1 @@
+export * from "./cli";

package/src/cli/plugins.ts

@@ -0,0 +1,13 @@
+import type { Plugin } from "./cli";
+
+import { configPlugin } from "../config";
+import { lintPlugin } from "../linter";
+import { buildPlugin } from "../builder";
+import { testPlugin } from "../tester";
+import { initPlugin } from "../init";
+
+export const commonPlugins: Plugin[] = [];
+
+export const nonProjectPlugins: Plugin[] = [initPlugin];
+
+export const projectBasedPlugins: Plugin[] = [configPlugin, lintPlugin, buildPlugin, testPlugin];

package/src/config/index.ts

@@ -0,0 +1,2 @@
+export * from "./projectConfig";
+export * from "./parsers";

package/src/config/parsers.ts

@@ -0,0 +1,40 @@
+import * as YAML from "js-yaml";
+
+/**
+ * If we want to add more built-in parsers,
+ * add them to this object with new file extension as the key,
+ * and a function that takes file content as string and returns parsed object as the value.
+ */
+export const parsers: { [key: string]: CustomParser } = {
+  // YAML
+  yml: {
+    extension: "yml",
+    parse: function <T>(content: string): T {
+      return YAML.load(content) as T;
+    },
+    stringify: function (content: any) {
+      return YAML.dump(content);
+    },
+  },
+
+  // JSON
+  json: {
+    extension: "json",
+    parse: function <T>(content: string): T {
+      return JSON.parse(content) as T;
+    },
+    stringify: function (content: any) {
+      return JSON.stringify(content, null, 2);
+    },
+  },
+};
+
+export type BuiltInParser = keyof typeof parsers; // keys of parsers object
+
+export interface CustomParser {
+  extension: string;
+  parse: <T>(content: string, filePath?: string) => T;
+  stringify: (content: any) => string;
+}
+
+export type Parser = BuiltInParser | CustomParser;

package/src/config/projectConfig.ts

@@ -0,0 +1,158 @@
+import * as path from "path";
+
+import { Parser, parsers } from "./parsers";
+import { FilesystemAdapter } from "../datasource/filesystemAdapter";
+import type { Plugin } from "../cli";
+
+export const EVENTS_DIRECTORY_NAME = "events";
+export const ATTRIBUTES_DIRECTORY_NAME = "attributes";
+export const DESTINATIONS_DIRECTORY_NAME = "destinations";
+export const STATES_DIRECTORY_NAME = "states";
+export const EFFECTS_DIRECTORY_NAME = "effects";
+export const TESTS_DIRECTORY_NAME = "tests";
+export const SYSTEM_DIRECTORY_NAME = ".eventvisor";
+export const DATAFILES_DIRECTORY_NAME = "datafiles";
+export const DATAFILE_NAME_PATTERN = "eventvisor-%s.json";
+export const SITE_EXPORT_DIRECTORY_NAME = "out";
+
+export const CONFIG_MODULE_NAME = "eventvisor.config.js";
+export const ROOT_DIR_PLACEHOLDER = "<rootDir>";
+
+export const DEFAULT_PRETTY_DATAFILE = false;
+
+export const DEFAULT_TAGS = ["all"];
+export const DEFAULT_PARSER: Parser = "yml";
+
+export const SCHEMA_VERSION = "1"; // default schema version
+
+export interface ProjectConfig {
+  eventsDirectoryPath: string;
+  attributesDirectoryPath: string;
+  destinationsDirectoryPath: string;
+  statesDirectoryPath: string;
+  effectsDirectoryPath: string;
+  testsDirectoryPath: string;
+  datafilesDirectoryPath: string;
+  systemDirectoryPath: string;
+  datafileNamePattern: string;
+
+  tags: string[];
+
+  adapter: any; // @NOTE: type this properly later
+  plugins: Plugin[];
+
+  parser: Parser;
+
+  prettyDatafile: boolean;
+  stringify: boolean;
+}
+
+// rootDirectoryPath: path to the root directory of the project (without ending with a slash)
+export function getProjectConfig(rootDirectoryPath: string): ProjectConfig {
+  const baseConfig: ProjectConfig = {
+    tags: DEFAULT_TAGS,
+
+    parser: DEFAULT_PARSER,
+
+    prettyDatafile: DEFAULT_PRETTY_DATAFILE,
+    stringify: true,
+
+    adapter: FilesystemAdapter,
+
+    eventsDirectoryPath: path.join(rootDirectoryPath, EVENTS_DIRECTORY_NAME),
+    attributesDirectoryPath: path.join(rootDirectoryPath, ATTRIBUTES_DIRECTORY_NAME),
+    destinationsDirectoryPath: path.join(rootDirectoryPath, DESTINATIONS_DIRECTORY_NAME),
+    statesDirectoryPath: path.join(rootDirectoryPath, STATES_DIRECTORY_NAME),
+    effectsDirectoryPath: path.join(rootDirectoryPath, EFFECTS_DIRECTORY_NAME),
+    testsDirectoryPath: path.join(rootDirectoryPath, TESTS_DIRECTORY_NAME),
+    datafilesDirectoryPath: path.join(rootDirectoryPath, DATAFILES_DIRECTORY_NAME),
+    datafileNamePattern: DATAFILE_NAME_PATTERN,
+    systemDirectoryPath: path.join(rootDirectoryPath, SYSTEM_DIRECTORY_NAME),
+
+    plugins: [],
+  };
+
+  const configModulePath = path.join(rootDirectoryPath, CONFIG_MODULE_NAME);
+  const customConfig = require(configModulePath);
+
+  const mergedConfig = {};
+
+  Object.keys(baseConfig).forEach((key) => {
+    mergedConfig[key] =
+      typeof customConfig[key] !== "undefined" ? customConfig[key] : baseConfig[key];
+
+    if (key.endsWith("Path") && mergedConfig[key].indexOf(ROOT_DIR_PLACEHOLDER) !== -1) {
+      mergedConfig[key] = mergedConfig[key].replace(ROOT_DIR_PLACEHOLDER, rootDirectoryPath);
+    }
+  });
+
+  const finalConfig = mergedConfig as ProjectConfig;
+
+  if (typeof finalConfig.parser === "string") {
+    const allowedParsers = Object.keys(parsers);
+    if (allowedParsers.indexOf(finalConfig.parser) === -1) {
+      throw new Error(`Invalid parser: ${finalConfig.parser}`);
+    }
+
+    finalConfig.parser = parsers[finalConfig.parser];
+  }
+
+  return finalConfig as ProjectConfig;
+}
+
+export interface ShowProjectConfigOptions {
+  json?: boolean;
+  pretty?: boolean;
+}
+
+export function showProjectConfig(
+  projectConfig: ProjectConfig,
+  options: ShowProjectConfigOptions = {},
+) {
+  if (options.json) {
+    console.log(
+      options.pretty ? JSON.stringify(projectConfig, null, 2) : JSON.stringify(projectConfig),
+    );
+
+    return;
+  }
+
+  console.log("\nProject configuration:\n");
+
+  const keys = Object.keys(projectConfig);
+  const longestKeyLength = keys.reduce((acc, key) => (key.length > acc ? key.length : acc), 0);
+  const ignoreKeys = ["adapter", "parser"];
+
+  for (const key of keys) {
+    if (ignoreKeys.indexOf(key) !== -1) {
+      continue;
+    }
+
+    console.log(`  - ${key.padEnd(longestKeyLength, " ")}: ${projectConfig[key]}`);
+  }
+}
+
+export const configPlugin: Plugin = {
+  command: "config",
+  handler: async ({ rootDirectoryPath, parsed }) => {
+    const projectConfig = getProjectConfig(rootDirectoryPath);
+    showProjectConfig(projectConfig, {
+      json: parsed.json,
+      pretty: parsed.pretty,
+    });
+  },
+  examples: [
+    {
+      command: "config",
+      description: "show the project configuration",
+    },
+    {
+      command: "config --print",
+      description: "show the project configuration as JSON",
+    },
+    {
+      command: "config --print --pretty",
+      description: "show the project configuration (as pretty JSON)",
+    },
+  ],
+};

package/src/datasource/adapter.ts

@@ -0,0 +1,23 @@
+import type { DatafileContent, EntityType } from "@eventvisor/types";
+
+export interface DatafileOptions {
+  tag: string;
+  datafilesDir?: string;
+}
+
+export abstract class Adapter {
+  // entities
+  abstract listEntities(entityType: EntityType): Promise<string[]>;
+  abstract entityExists(entityType: EntityType, entityKey: string): Promise<boolean>;
+  abstract readEntity<T>(entityType: EntityType, entityKey: string): Promise<T>;
+  abstract writeEntity<T>(entityType: EntityType, entityKey: string, entity: T): Promise<T>;
+  abstract deleteEntity(entityType: EntityType, entityKey: string): Promise<void>;
+
+  // datafile
+  abstract readDatafile(options: DatafileOptions): Promise<DatafileContent>;
+  abstract writeDatafile(datafileContent: DatafileContent, options: DatafileOptions): Promise<void>;
+
+  // revision
+  abstract readRevision(): Promise<string>;
+  abstract writeRevision(revision: string): Promise<void>;
+}

package/src/datasource/datasource.ts

@@ -0,0 +1,164 @@
+import type {
+  Event,
+  EventName,
+  Attribute,
+  AttributeName,
+  Destination,
+  DestinationName,
+  Effect,
+  EffectName,
+  Test,
+  TestName,
+  DatafileContent,
+} from "@eventvisor/types";
+
+import { ProjectConfig, CustomParser } from "../config";
+
+import { Adapter, DatafileOptions } from "./adapter";
+
+export class Datasource {
+  private adapter: Adapter;
+
+  constructor(
+    private config: ProjectConfig,
+    private rootDirectoryPath?: string,
+  ) {
+    this.adapter = new config.adapter(config, rootDirectoryPath);
+  }
+
+  // @NOTE: only site generator needs it, find a way to get it out of here later
+  getExtension() {
+    return (this.config.parser as CustomParser).extension;
+  }
+
+  /**
+   * Revision
+   */
+  readRevision() {
+    return this.adapter.readRevision();
+  }
+
+  writeRevision(revision: string) {
+    return this.adapter.writeRevision(revision);
+  }
+
+  /**
+   * Datafile
+   */
+  readDatafile(options: DatafileOptions) {
+    return this.adapter.readDatafile(options);
+  }
+
+  writeDatafile(datafileContent: DatafileContent, options: DatafileOptions) {
+    return this.adapter.writeDatafile(datafileContent, options);
+  }
+
+  /**
+   * Entity specific methods
+   */
+
+  // events
+  listEvents() {
+    return this.adapter.listEntities("event");
+  }
+
+  eventExists(eventName: EventName) {
+    return this.adapter.entityExists("event", eventName);
+  }
+
+  readEvent(eventName: EventName) {
+    return this.adapter.readEntity<Event>("event", eventName);
+  }
+
+  writeEvent(eventName: EventName, event: Event) {
+    return this.adapter.writeEntity<Event>("event", eventName, event);
+  }
+
+  deleteEvent(eventName: EventName) {
+    return this.adapter.deleteEntity("event", eventName);
+  }
+
+  // attributes
+  listAttributes() {
+    return this.adapter.listEntities("attribute");
+  }
+
+  attributeExists(attributeName: AttributeName) {
+    return this.adapter.entityExists("attribute", attributeName);
+  }
+
+  readAttribute(attributeName: AttributeName) {
+    return this.adapter.readEntity<Attribute>("attribute", attributeName);
+  }
+
+  writeAttribute(attributeName: AttributeName, attribute: Attribute) {
+    return this.adapter.writeEntity<Attribute>("attribute", attributeName, attribute);
+  }
+
+  deleteAttribute(attributeName: AttributeName) {
+    return this.adapter.deleteEntity("attribute", attributeName);
+  }
+
+  // destinations
+  listDestinations() {
+    return this.adapter.listEntities("destination");
+  }
+
+  destinationExists(destinationName: DestinationName) {
+    return this.adapter.entityExists("destination", destinationName);
+  }
+
+  readDestination(destinationName: DestinationName) {
+    return this.adapter.readEntity<Destination>("destination", destinationName);
+  }
+
+  writeDestination(destinationName: DestinationName, destination: Destination) {
+    return this.adapter.writeEntity<Destination>("destination", destinationName, destination);
+  }
+
+  deleteDestination(destinationName: DestinationName) {
+    return this.adapter.deleteEntity("destination", destinationName);
+  }
+
+  // effects
+  listEffects() {
+    return this.adapter.listEntities("effect");
+  }
+
+  effectExists(effectName: EffectName) {
+    return this.adapter.entityExists("effect", effectName);
+  }
+
+  readEffect(effectName: EffectName) {
+    return this.adapter.readEntity<Effect>("effect", effectName);
+  }
+
+  writeEffect(effectName: EffectName, effect: Effect) {
+    return this.adapter.writeEntity<Effect>("effect", effectName, effect);
+  }
+
+  deleteEffect(effectName: EffectName) {
+    return this.adapter.deleteEntity("effect", effectName);
+  }
+
+  // tests
+  listTests() {
+    return this.adapter.listEntities("test");
+  }
+
+  readTest(testName: TestName) {
+    return this.adapter.readEntity<Test>("test", testName);
+  }
+
+  writeTest(testName: TestName, test: Test) {
+    return this.adapter.writeEntity<Test>("test", testName, test);
+  }
+
+  deleteTest(testName: TestName) {
+    return this.adapter.deleteEntity("test", testName);
+  }
+
+  getTestSpecName(testName: TestName) {
+    return `${testName}.${this.getExtension()}`;
+  }
+}