Merge pull request #10 from event-catalog/adding-commands-to-sdk

feat(sdk): added commands to sdk

.changeset/chilled-trainers-obey.md

@@ -0,0 +1,5 @@
+---
+"@eventcatalog/sdk": patch
+---
+
+feat(sdk): added commands to sdk

src/commands.ts

@@ -0,0 +1,185 @@
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import type { Command } from './types';
+import { addFileToResource, getResource, rmResourceById, versionResource, writeResource } from './internal/resources';
+
+/**
+ * Returns a command from EventCatalog.
+ *
+ * You can optionally specify a version to get a specific version of the command
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getCommand } = utils('/path/to/eventcatalog');
+ *
+ * // Gets the latest version of the command
+ * const command = await getCommand('UpdateInventory');
+ *
+ * // Gets a version of the command
+ * const command = await getCommand('UpdateInventory', '0.0.1');
+ * ```
+ */
+export const getCommand =
+  (directory: string) =>
+  async (id: string, version?: string): Promise<Command> =>
+    getResource(directory, id, version, { type: 'command' }) as Promise<Command>;
+
+/**
+ * Write a command to EventCatalog.
+ *
+ * You can optionally override the path of the command.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeCommand } = utils('/path/to/eventcatalog');
+ *
+ * // Write a command to the catalog
+ * // Command would be written to commands/UpdateInventory
+ * await writeCommand({
+ *   id: 'UpdateInventory',
+ *   name: 'Update Inventory',
+ *   version: '0.0.1',
+ *   summary: 'This is a summary',
+ *   markdown: '# Hello world',
+ * });
+ *
+ * // Write a command to the catalog but override the path
+ * // Command would be written to commands/Inventory/UpdateInventory
+ * await writeCommand({
+ *    id: 'UpdateInventory',
+ *    name: 'Update Inventory',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ * }, { path: "/Inventory/UpdateInventory"});
+ * ```
+ */
+export const writeCommand =
+  (directory: string) =>
+  async (command: Command, options: { path: string } = { path: '' }) =>
+    writeResource(directory, { ...command }, { ...options, type: 'command' });
+
+/**
+ * Delete a command at it's given path.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmCommand } = utils('/path/to/eventcatalog');
+ *
+ * // removes a command at the given path (commands dir is appended to the given path)
+ * // Removes the command at commands/UpdateInventory
+ * await rmCommand('/UpdateInventory');
+ * ```
+ */
+export const rmCommand = (directory: string) => async (path: string) => {
+  await fs.rm(join(directory, path), { recursive: true });
+};
+
+/**
+ * Delete a command by it's id.
+ *
+ * Optionally specify a version to delete a specific version of the command.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmCommandById } = utils('/path/to/eventcatalog');
+ *
+ * // deletes the latest UpdateInventory command
+ * await rmCommandById('UpdateInventory');
+ *
+ * // deletes a specific version of the UpdateInventory command
+ * await rmCommandById('UpdateInventory', '0.0.1');
+ * ```
+ */
+export const rmCommandById = (directory: string) => async (id: string, version?: string) =>
+  rmResourceById(directory, id, version, { type: 'command' });
+
+/**
+ * Version a command by it's id.
+ *
+ * Takes the latest command and moves it to a versioned directory.
+ * All files with this command are also versioned (e.g /commands/UpdateInventory/schema.json)
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { versionCommand } = utils('/path/to/eventcatalog');
+ *
+ * // moves the latest UpdateInventory command to a versioned directory
+ * // the version within that command is used as the version number.
+ * await versionCommand('UpdateInventory');
+ *
+ * ```
+ */
+export const versionCommand = (directory: string) => async (id: string) => versionResource(directory, id);
+
+/**
+ * Add a file to a command by it's id.
+ *
+ * Optionally specify a version to add a file to a specific version of the command.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addFileToCommand } = utils('/path/to/eventcatalog');
+ *
+ * // adds a file to the latest UpdateInventory command
+ * await addFileToCommand('UpdateInventory', { content: 'Hello world', fileName: 'hello.txt' });
+ *
+ * // adds a file to a specific version of the UpdateInventory command
+ * await addFileToCommand('UpdateInventory', { content: 'Hello world', fileName: 'hello.txt' }, '0.0.1');
+ *
+ * ```
+ */
+export const addFileToCommand =
+  (directory: string) => async (id: string, file: { content: string; fileName: string }, version?: string) =>
+    addFileToResource(directory, id, file, version);
+
+/**
+ * Add a schema to a command by it's id.
+ *
+ * Optionally specify a version to add a schema to a specific version of the command.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addSchemaToCommand } = utils('/path/to/eventcatalog');
+ *
+ * // JSON schema example
+ * const schema = {
+ *    "$schema": "http://json-schema.org/draft-07/schema#",
+ *    "type": "object",
+ *    "properties": {
+ *        "name": {
+ *        "type": "string"
+ *    },
+ *    "age": {
+ *      "type": "number"
+ *    }
+ *  },
+ *  "required": ["name", "age"]
+ * };
+ *
+ * // adds a schema to the latest UpdateInventory command
+ * await addSchemaToCommand('UpdateInventory', { schema, fileName: 'schema.json' });
+ *
+ * // adds a file to a specific version of the UpdateInventory command
+ * await addSchemaToCommand('UpdateInventory', { schema, fileName: 'schema.json' }, '0.0.1');
+ *
+ * ```
+ */
+export const addSchemaToCommand =
+  (directory: string) => async (id: string, schema: { schema: string; fileName: string }, version?: string) => {
+    await addFileToCommand(directory)(id, { content: schema.schema, fileName: schema.fileName }, version);
+  };

src/docs.ts

@@ -27,3 +27,4 @@
  */
 export * from './events';
 export * from './services';
+export * from './commands';

src/events.ts

@@ -18,10 +18,10 @@ import { addFileToResource, getResource, rmResourceById, versionResource, writeR
  * const { getEvent } = utils('/path/to/eventcatalog');
  *
  * // Gets the latest version of the event
- * cont event = await getEvent('InventoryAdjusted');
+ * const event = await getEvent('InventoryAdjusted');
  *
  * // Gets a version of the event
- * cont event = await getEvent('InventoryAdjusted', '0.0.1');
+ * const event = await getEvent('InventoryAdjusted', '0.0.1');
  * ```
  */
 export const getEvent =
@@ -151,7 +151,7 @@ export const addFileToEvent =
 /**
  * Add a schema to an event by it's id.
  *
- * Optionally specify a version to add a schame to a specific version of the event.
+ * Optionally specify a version to add a schema to a specific version of the event.
  *
  * @example
  * ```ts

src/index.ts

@@ -1,5 +1,14 @@
 import { join } from 'node:path';
 import { rmEvent, rmEventById, writeEvent, versionEvent, getEvent, addFileToEvent, addSchemaToEvent } from './events';
+import {
+  rmCommand,
+  rmCommandById,
+  writeCommand,
+  versionCommand,
+  getCommand,
+  addFileToCommand,
+  addSchemaToCommand,
+} from './commands';
 import { writeService, getService, versionService, rmService, rmServiceById, addFileToService } from './services';
 
 /**
@@ -61,6 +70,63 @@ export default (path: string) => {
      */
     addSchemaToEvent: addSchemaToEvent(join(path, 'events')),
 
+    /**
+     * ================================
+     *            Commands
+     * ================================
+     */
+
+    /**
+     * Returns a command from EventCatalog
+     * @param id - The id of the command to retrieve
+     * @param version - Optional id of the version to get
+     * @returns
+     */
+    getCommand: getCommand(join(path, 'commands')),
+    /**
+     * Adds an command to EventCatalog
+     *
+     * @param command - The command to write
+     * @param options - Optional options to write the command
+     *
+     */
+    writeCommand: writeCommand(join(path, 'commands')),
+    /**
+     * Remove an command to EventCatalog (modeled on the standard POSIX rm utility)
+     *
+     * @param path - The path to your command, e.g. `/Inventory/InventoryAdjusted`
+     *
+     */
+    rmCommand: rmCommand(join(path, 'commands')),
+    /**
+     * Remove an command by an Event id
+     *
+     * @param id - The id of the command you want to remove
+     *
+     */
+    rmCommandById: rmCommandById(join(path, 'commands')),
+    /**
+     * Moves a given command id to the version directory
+     * @param directory
+     */
+    versionCommand: versionCommand(join(path, 'commands')),
+    /**
+     * Adds a file to the given command
+     * @param id - The id of the command to add the file to
+     * @param file - File contents to add including the content and the file name
+     * @param version - Optional version of the command to add the file to
+     * @returns
+     */
+    addFileToCommand: addFileToCommand(join(path, 'commands')),
+    /**
+     * Adds a schema to the given command
+     * @param id - The id of the command to add the schema to
+     * @param schema - Schema contents to add including the content and the file name
+     * @param version - Optional version of the command to add the schema to
+     * @returns
+     */
+    addSchemaToCommand: addSchemaToCommand(join(path, 'commands')),
+
     /**
      * ================================
      *            SERVICES

src/services.ts

@@ -17,10 +17,10 @@ import { addFileToResource, getResource, rmResourceById, versionResource, writeR
  * const { getService } = utils('/path/to/eventcatalog');
  *
  * // Gets the latest version of the event
- * cont event = await getService('InventoryService');
+ * const service = await getService('InventoryService');
  *
  * // Gets a version of the event
- * cont event = await getService('InventoryService', '0.0.1');
+ * const service = await getService('InventoryService', '0.0.1');
  * ```
  */
 export const getService =