@kravc/dos 1.12.6 → 2.0.0-alpha.0

package/src/Operation/errors/InvalidParametersError.ts

@@ -0,0 +1,30 @@
+import CommonError from './CommonError';
+
+/**
+ * Invalid Parameters Error
+ *
+ * `InvalidParametersError` represents a **400 Bad Request** error that occurs when operation
+ * parameters are syntactically correct (pass schema validation) but are semantically invalid or
+ * not processible by the operation logic. This is distinct from `InvalidInputError`, which
+ * indicates schema validation failures.
+ *
+ * This error signals that:
+ *
+ * - The input structure and types are valid according to the schema
+ * - However, the parameter values are invalid for the specific operation context
+ * - The operation cannot proceed with the provided parameters
+ *
+ * This error is typically thrown manually by operation implementations when they detect
+ * invalid parameter combinations or values that cannot be validated by the schema alone.
+ * For example, an operation might accept a date range where the start date must be before
+ * the end date—this business rule cannot be expressed in JSON Schema, so the operation
+ * would throw `InvalidParametersError` if violated.
+ */
+class InvalidParametersError extends CommonError {
+  /** Creates an instance of invalid parameters error. */
+  constructor(message: string = 'Invalid parameters') {
+    super('InvalidParametersError', message);
+  }
+}
+
+export default InvalidParametersError;

package/src/Operation/errors/UnauthorizedError.ts

@@ -0,0 +1,28 @@
+import CommonError from './CommonError';
+
+/**
+ * Unauthorized Error
+ *
+ * `UnauthorizedError` represents a **401 Unauthorized** error that occurs when authentication
+ * fails—the request lacks valid credentials or the provided credentials are invalid. This is
+ * distinct from `AccessDeniedError` (403), which indicates that authentication succeeded but
+ * authorization failed (the user lacks permissions).
+ *
+ * This error signals that:
+ *
+ * - The request is missing required authentication credentials (e.g., Authorization header, token)
+ * - The provided credentials are invalid, expired, or malformed
+ * - The client must provide valid authentication before the request can proceed
+ *
+ * This error is thrown by security authorization classes (`JwtAuthorization`, `SystemAuthorization`)
+ * during the authentication phase, before any operation logic executes. The framework automatically
+ * returns this error with a 401 status code, indicating that the client needs to authenticate.
+ */
+class UnauthorizedError extends CommonError {
+  /** Creates an instance of unauthorized error. */
+  constructor(message: string) {
+    super('UnauthorizedError', message);
+  }
+}
+
+export default UnauthorizedError;

package/src/Operation/errors/UnprocessibleConditionError.ts

@@ -0,0 +1,32 @@
+import CommonError from './CommonError';
+
+/**
+ * Unprocessible Condition Error
+ *
+ * `UnprocessibleConditionError` represents a **422 Unprocessable Entity** error that occurs
+ * when an operation encounters an expected exit condition that prevents it from processing
+ * the request. This error indicates that the request is well-formed and valid, but the
+ * operation cannot proceed due to business logic constraints or state conditions.
+ *
+ * This error signals that:
+ *
+ * - The request syntax and structure are valid (input passes schema validation)
+ * - The operation cannot be completed due to business rules or state constraints
+ * - The condition is expected and part of normal operation flow (not a bug)
+ *
+ * This is distinct from other error types:
+ * - **400 (InvalidInputError/InvalidParametersError)**: Input validation failures
+ * - **404 (DocumentNotFoundError)**: Resource doesn't exist
+ * - **500 (InvalidOutputError)**: Internal bugs
+ *
+ * The 422 status code indicates that the server understands the request but cannot process
+ * it due to semantic errors or business logic constraints.
+ */
+class UnprocessibleConditionError extends CommonError {
+  /** Creates an instance of unprocessible condition error. */
+  constructor(message: string = 'Unprocessible condition') {
+    super('UnprocessibleConditionError', message);
+  }
+}
+
+export default UnprocessibleConditionError;

package/src/Operation/errors/__tests__/InvalidParametersError.test.ts

@@ -0,0 +1,20 @@
+import InvalidParametersError from '../InvalidParametersError';
+
+describe('InvalidParametersError', () => {
+  describe('InvalidParametersError.constructor(message)', () => {
+    it('creates an instance with default message when no message is provided', () => {
+      const err = new InvalidParametersError();
+
+      expect(err.code).toBe('InvalidParametersError');
+      expect(err.message).toBe('Invalid parameters');
+    });
+
+    it('creates an instance with custom message when provided', () => {
+      const customMessage = 'Start date must be before end date';
+      const err = new InvalidParametersError(customMessage);
+
+      expect(err.code).toBe('InvalidParametersError');
+      expect(err.message).toBe(customMessage);
+    });
+  });
+});

package/src/Operation/errors/__tests__/UnprocessibleConditionError.test.ts

@@ -0,0 +1,20 @@
+import UnprocessibleConditionError from '../UnprocessibleConditionError';
+
+describe('UnprocessibleConditionError', () => {
+  describe('UnprocessibleConditionError.constructor(message)', () => {
+    it('creates an instance with default message when no message is provided', () => {
+      const err = new UnprocessibleConditionError();
+
+      expect(err.code).toBe('UnprocessibleConditionError');
+      expect(err.message).toBe('Unprocessible condition');
+    });
+
+    it('creates an instance with custom message when provided', () => {
+      const customMessage = 'Order is already cancelled';
+      const err = new UnprocessibleConditionError(customMessage);
+
+      expect(err.code).toBe('UnprocessibleConditionError');
+      expect(err.message).toBe(customMessage);
+    });
+  });
+});

package/src/Operation/errors/index.ts

@@ -0,0 +1,17 @@
+import CommonError from './CommonError';
+import UnauthorizedError from './UnauthorizedError';
+import AccessDeniedError from './AccessDeniedError';
+import DocumentExistsError from './DocumentExistsError';
+import DocumentNotFoundError from './DocumentNotFoundError';
+import InvalidParametersError from './InvalidParametersError';
+import UnprocessibleConditionError from './UnprocessibleConditionError';
+
+export {
+  CommonError,
+  UnauthorizedError,
+  AccessDeniedError,
+  DocumentExistsError,
+  DocumentNotFoundError,
+  InvalidParametersError,
+  UnprocessibleConditionError,
+};

package/src/Operation/helpers/index.ts

@@ -0,0 +1,9 @@
+import withActivity, { type CreateActivityProps } from './withActivity';
+
+export {
+  withActivity
+};
+
+export type {
+  CreateActivityProps
+};

package/src/Operation/helpers/withActivity.ts

@@ -0,0 +1,43 @@
+import Create from '../operations/Create';
+import Update from '../operations/Update';
+import Delete from '../operations/Delete';
+import Context from '../../Context';
+import Operation, { type Result } from '../Operation';
+
+type BaseAction = typeof Create | typeof Update | typeof Delete;
+
+export type CreateActivityProps = {
+  result?: Result;
+  context: Context;
+  parameters: Record<string, unknown>;
+  componentName?: string;
+}
+
+/** Extends operation with a custom create activity method. */
+const withActivity = (
+  baseAction: BaseAction,
+  createActivity: (props: CreateActivityProps) => Promise<void>
+): (ComponentClass: unknown, componentAction?: string) => typeof Operation => {
+  return (ComponentClass, componentAction) => {
+    /** Operation class with create activity method. */
+    return class extends baseAction(ComponentClass, componentAction) {
+      /** Creates activity after default exec is done */
+      async createActivity(
+        parameters: Record<string, unknown>,
+        result?: Result
+      ): Promise<void> {
+        const context = this.context;
+        const { componentName } = this.constructor as typeof Operation;
+
+        await createActivity({
+          result,
+          context,
+          parameters,
+          componentName,
+        });
+      }
+    };
+  };
+};
+
+export default withActivity;

package/src/Operation/index.ts

@@ -0,0 +1,29 @@
+import Operation from './Operation';
+
+import Read from './operations/Read';
+import List from './operations/List';
+import Index from './operations/Index';
+import Create from './operations/Create';
+import Update from './operations/Update';
+import Delete from './operations/Delete';
+import { withActivity, type CreateActivityProps } from './helpers';
+
+export default Operation;
+
+export {
+  Read,
+  List,
+  Index,
+  Create,
+  Update,
+  Delete,
+  Operation,
+  withActivity,
+};
+
+export * from './errors';
+export * from './security';
+
+export type {
+  CreateActivityProps
+};

package/src/Operation/operations/Create.ts

@@ -0,0 +1,49 @@
+import Operation from '../Operation';
+import Component from '../../Component';
+
+/** Returns class for a create operation. */
+const Create = (
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ComponentClass: any,
+  componentAction: string = Operation.types.CREATE
+): typeof Operation => {
+  if (!ComponentClass?.isComponent) {
+    throw new Error('Argument "ComponentClass" is undefined for "Create" operation' +
+      ' function');
+  }
+
+  ComponentClass = ComponentClass as unknown as typeof Component;
+
+  const componentTitle = ComponentClass.getTitle();
+
+  /** Create operation class */
+  return class extends Operation {
+    /** Returns component class for a create operation. */
+    static get Component() {
+      return ComponentClass;
+    }
+
+    /** Returns component action name for a create operation. */
+    static get componentAction() {
+      return componentAction;
+    }
+
+    /** Returns create operation type. */
+    static get type() {
+      return Operation.types.CREATE;
+    }
+
+    /** Returns possible errors for a create operation. */
+    static get errors() {
+      return {
+        ...super.errors,
+        DocumentExistsError: {
+          statusCode: 422,
+          description: `${componentTitle} could not be created, it already exists`
+        }
+      };
+    }
+  };
+};
+
+export default Create;

package/src/Operation/operations/Delete.ts

@@ -0,0 +1,65 @@
+import Operation from '../Operation';
+import Component from '../../Component';
+
+/** Returns class for a delete operation. */
+const Delete = (
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ComponentClass: any,
+  componentAction: string = Operation.types.DELETE
+): typeof Operation => {
+  if (!ComponentClass?.isComponent) {
+    throw new Error('Argument "ComponentClass" is undefined for "Delete" operation' +
+      ' function');
+  }
+
+  ComponentClass = ComponentClass as unknown as typeof Component;
+
+  const componentTitle = ComponentClass.getTitle();
+  const componentTitleLower = componentTitle.toLowerCase();
+
+  /** Delete operation class */
+  return class extends Operation {
+    /** Returns component class for a delete operation. */
+    static get Component() {
+      return ComponentClass;
+    }
+
+    /** Returns component action name for a delete operation. */
+    static get componentAction() {
+      return componentAction;
+    }
+
+    /** Returns delete operation type. */
+    static get type() {
+      return Operation.types.DELETE;
+    }
+
+    /** Returns possible errors for a delete operation. */
+    static get errors() {
+      return {
+        ...super.errors,
+        DocumentNotFoundError: {
+          statusCode: 404,
+          description: `${componentTitle} is not found`
+        }
+      };
+    }
+
+    /** Returns query schema with a component ID. */
+    static get query() {
+      return {
+        id: {
+          description: `ID of ${componentTitleLower} to be deleted`,
+          required: true
+        }
+      };
+    }
+
+    /** No output for a delete operation. */
+    static get output() {
+      return null;
+    }
+  };
+};
+
+export default Delete;

package/src/Operation/operations/Index.ts

@@ -0,0 +1,164 @@
+import Component from '../../Component';
+import { capitalize } from 'lodash';
+import Operation, { type Result } from '../Operation';
+import { type PropertiesSchemaSource } from '@kravc/schema';
+
+const SORT_ORDER = {
+  ASC: 'asc',
+  DESC: 'desc',
+};
+
+const DEFAULT_LIMIT = 20;
+const DEFAULT_LIMIT_MAX = 999;
+const DEFAULT_SORT_ORDER = SORT_ORDER.DESC;
+
+export type PageInfo = {
+  sort: 'asc' | 'desc';
+  count: number;
+  limit: number;
+  lastEvaluatedKey?: string;
+}
+
+/** Returns class for an index operation. */
+const Index = (
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ComponentClass: any,
+  componentAction: string = 'index'
+): typeof Operation => {
+  if (!ComponentClass?.isComponent) {
+    throw new Error('Argument "ComponentClass" is undefined for "Index"' +
+      ' operation function');
+  }
+
+  ComponentClass = ComponentClass as unknown as typeof Component;
+
+  const documentTitle = ComponentClass.getTitle(false, true);
+
+  /** Index operation class */
+  return class extends Operation {
+    /** Returns summary for an index operation. */
+    static get summary() {
+      return capitalize(`${componentAction} ${documentTitle}`);
+    }
+
+    /** Returns component class for an index operation. */
+    static get Component() {
+      return ComponentClass;
+    }
+
+    /** Returns component action name for an index operation. */
+    static get componentAction() {
+      return componentAction;
+    }
+
+    /** Returns default value for a limit parameter. */
+    static get defaultLimit() {
+      return DEFAULT_LIMIT;
+    }
+
+    /** Returns maximum number for a limit parameter. */
+    static get limitMax() {
+      return DEFAULT_LIMIT_MAX;
+    }
+
+    /** Returns default value for a sort parameter. */
+    static get defaultSort() {
+      return DEFAULT_SORT_ORDER;
+    }
+
+    /** Returns query schema for pagination parameters. */
+    static get query() {
+      return {
+        limit: {
+          type: 'integer',
+          example: this.defaultLimit,
+          default: this.defaultLimit,
+          minimum: 1,
+          maximum: this.limitMax,
+          description: `Limit number of ${documentTitle} to be returned`,
+        },
+        sort: {
+          enum: Object.values(SORT_ORDER),
+          default: this.defaultSort,
+          description: 'Sort direction',
+        },
+        exclusiveStartKey: {
+          description: `Exclusive start key to return next batch of ${documentTitle}`,
+        }
+      } as PropertiesSchemaSource;
+    }
+
+    /** Returns schema source for the operation output with pagination. */
+    static get output() {
+      return {
+        data: {
+          items: {
+            $ref: ComponentClass.schema!.id
+          },
+          required: true,
+        },
+        pageInfo: {
+          required: true,
+          properties: {
+            sort: {
+              enum: Object.values(SORT_ORDER),
+              description: 'Sort direction',
+            },
+            count: {
+              type: 'integer',
+              example: 0,
+              description: `Number of ${documentTitle}`,
+            },
+            limit: {
+              type: 'integer',
+              example: 100,
+              description: `Limit number of ${documentTitle} to be returned`,
+            },
+            lastEvaluatedKey: {
+              description: `Last evaluated key to get next batch of ${documentTitle}`,
+            },
+          }
+        }
+      };
+    }
+
+    /** Executes components index action. */
+    async action(parameters: Record<string, unknown>) {
+      const {
+        sort,
+        limit,
+        index,
+        exclusiveStartKey,
+        ...query
+      } = parameters;
+
+      const options = {
+        sort,
+        limit,
+        index,
+        exclusiveStartKey,
+      };
+
+      const { componentActionMethod } = this.constructor as typeof Operation;
+
+      const result = await componentActionMethod(this.context, query, options);
+
+      const {
+        objects: data,
+        count,
+        lastEvaluatedKey,
+      } = result;
+
+      const pageInfo = {
+        sort,
+        count,
+        limit,
+        lastEvaluatedKey,
+      } as PageInfo;
+
+      return { data, pageInfo } as { data: Result, pageInfo: PageInfo };
+    }
+  };
+};
+
+export default Index;

package/src/Operation/operations/List.ts

@@ -0,0 +1,62 @@
+import Component from '../../Component';
+import { capitalize } from 'lodash';
+import Operation, { type Result } from '../Operation';
+
+/** Returns class for an list operation. */
+const List = (
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ComponentClass: any,
+  componentAction: string = 'indexAll'
+): typeof Operation => {
+  if (!ComponentClass?.isComponent) {
+    throw new Error('Argument "ComponentClass" is undefined for "List"' +
+      ' operation function');
+  }
+
+  ComponentClass = ComponentClass as unknown as typeof Component;
+
+  const documentTitle = ComponentClass.getTitle(false, true);
+
+  /** List operation class */
+  return class extends Operation {
+    /** Returns summary for an index operation. */
+    static get summary() {
+      const action = componentAction.replace('indexAll', 'list');
+      return capitalize(`${action} ${documentTitle}`);
+    }
+
+    /** Returns component class for an index operation. */
+    static get Component() {
+      return ComponentClass;
+    }
+
+    /** Returns component action name for an index operation. */
+    static get componentAction() {
+      return componentAction;
+    }
+
+    /** Executes components list action. */
+    async action(parameters: Record<string, unknown>) {
+      const {
+        sort,
+        index,
+        ...query
+      } = parameters;
+
+      const options = {
+        sort,
+        index,
+      };
+
+      const { componentActionMethod } = this.constructor as typeof Operation;
+
+      const result = await componentActionMethod(this.context, query, options);
+
+      const { objects } = result;
+
+      return { data: objects } as { data: Result };
+    }
+  };
+};
+
+export default List;

package/src/Operation/operations/Read.ts

@@ -0,0 +1,55 @@
+import Operation from '../Operation';
+import Component from '../../Component';
+
+/** Returns class for a read operation. */
+const Read = (
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ComponentClass: any,
+  componentAction: string = Operation.types.READ
+): typeof Operation => {
+  if (!ComponentClass?.isComponent) {
+    throw new Error('Argument "ComponentClass" is undefined for "Read" operation' +
+      ' function');
+  }
+
+  ComponentClass = ComponentClass as unknown as typeof Component;
+
+  const componentTitle = ComponentClass.getTitle();
+  const componentTitleLower = componentTitle.toLowerCase();
+
+  /** Read operation class */
+  return class extends Operation {
+    /** Returns component class for a read operation. */
+    static get Component() {
+      return ComponentClass;
+    }
+
+    /** Returns component action name for a read operation. */
+    static get componentAction() {
+      return componentAction;
+    }
+
+    /** Returns possible errors for a read operation. */
+    static get errors() {
+      return {
+        ...super.errors,
+        DocumentNotFoundError: {
+          statusCode:  404,
+          description: `${componentTitle} is not found`
+        }
+      };
+    }
+
+    /** Returns query schema with a component ID. */
+    static get query() {
+      return {
+        id: {
+          description: `ID of ${componentTitleLower} to be returned`,
+          required: true
+        }
+      };
+    }
+  };
+};
+
+export default Read;