@emkodev/emkore 1.0.3

package/src/common/validation/validators.ts

@@ -0,0 +1,441 @@
+import { ValidationResult } from "./validation-result.ts";
+import type {
+  JsonSchema,
+  JsonSchemaType,
+  MutableJsonSchema,
+} from "../type/json-schema.type.ts";
+
+export class ValidationError {
+  constructor(public readonly message: string) {}
+
+  toString(): string {
+    return this.message;
+  }
+}
+
+export class ValidatorBuilder {
+  private _schema: MutableJsonSchema = { type: "object", properties: {} };
+  private _errors: ValidationError[] = [];
+
+  constructor(private readonly _prefix?: string) {}
+
+  string(
+    field: string,
+    value: string | null | undefined,
+    options: {
+      required?: boolean;
+      minLength?: number;
+      maxLength?: number;
+      pattern?: string;
+    } = {},
+  ): ValidatorBuilder {
+    const { required = false, minLength, maxLength, pattern } = options;
+    const fullField = this._prefix ? `${this._prefix}.${field}` : field;
+
+    if (!this._schema.properties) {
+      this._schema.properties = {};
+    }
+    this._schema.properties[field] = {
+      type: "string",
+      ...(required && { required: true }),
+      ...(minLength !== undefined && { minLength }),
+      ...(maxLength !== undefined && { maxLength }),
+      ...(pattern && { pattern }),
+    };
+
+    if (required && (!value || value.trim() === "")) {
+      this._errors.push(new ValidationError(`${fullField} is required`));
+    } else if (value) {
+      if (minLength !== undefined && value.length < minLength) {
+        this._errors.push(
+          new ValidationError(
+            `${fullField} must be at least ${minLength} characters`,
+          ),
+        );
+      }
+      if (maxLength !== undefined && value.length > maxLength) {
+        this._errors.push(
+          new ValidationError(
+            `${fullField} must be at most ${maxLength} characters`,
+          ),
+        );
+      }
+      if (pattern && !new RegExp(pattern).test(value)) {
+        this._errors.push(
+          new ValidationError(`${fullField} format is invalid`),
+        );
+      }
+    }
+
+    return this;
+  }
+
+  email(
+    field: string,
+    value: string | null | undefined,
+    required = false,
+  ): ValidatorBuilder {
+    return this.string(field, value, {
+      required,
+      pattern: /^[^@]+@[^@]+\.[^@]+$/.source,
+    });
+  }
+
+  uuid(
+    field: string,
+    value: string | null | undefined,
+    required = false,
+  ): ValidatorBuilder {
+    return this.string(field, value, {
+      required,
+      pattern: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+        .source,
+    });
+  }
+
+  entityId(
+    field: string,
+    value: string | null | undefined,
+    prefix: string,
+    required = false,
+  ): ValidatorBuilder {
+    const fullField = this._prefix ? `${this._prefix}.${field}` : field;
+
+    if (!this._schema.properties) {
+      this._schema.properties = {};
+    }
+    this._schema.properties[field] = {
+      type: "string",
+      ...(required && { required: true }),
+      pattern:
+        /^[0-9a-f]{4}-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+          .source,
+    };
+
+    if (required && (!value || value === "")) {
+      this._errors.push(new ValidationError(`${fullField} is required`));
+    } else if (value) {
+      const entityIdRegex =
+        /^[0-9a-f]{4}-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+      if (!entityIdRegex.test(value)) {
+        this._errors.push(
+          new ValidationError(
+            `${fullField} must be in format xxxx-{uuid} where xxxx is a 4-hex-character prefix`,
+          ),
+        );
+      } else if (!value.toLowerCase().startsWith(`${prefix.toLowerCase()}-`)) {
+        this._errors.push(
+          new ValidationError(`${fullField} must start with prefix ${prefix}`),
+        );
+      }
+    }
+
+    return this;
+  }
+
+  number(
+    field: string,
+    value: number | null | undefined,
+    options: {
+      required?: boolean;
+      min?: number;
+      max?: number;
+    } = {},
+  ): ValidatorBuilder {
+    const { required = false, min, max } = options;
+    const fullField = this._prefix ? `${this._prefix}.${field}` : field;
+
+    if (!this._schema.properties) {
+      this._schema.properties = {};
+    }
+    this._schema.properties[field] = {
+      type: "number",
+      ...(required && { required: true }),
+      ...(min !== undefined && { minimum: min }),
+      ...(max !== undefined && { maximum: max }),
+    };
+
+    if (required && value == null) {
+      this._errors.push(new ValidationError(`${fullField} is required`));
+    } else if (value != null) {
+      if (min !== undefined && value < min) {
+        this._errors.push(
+          new ValidationError(`${fullField} must be at least ${min}`),
+        );
+      }
+      if (max !== undefined && value > max) {
+        this._errors.push(
+          new ValidationError(`${fullField} must be at most ${max}`),
+        );
+      }
+    }
+
+    return this;
+  }
+
+  integer(
+    field: string,
+    value: number | null | undefined,
+    options: {
+      required?: boolean;
+      min?: number;
+      max?: number;
+    } = {},
+  ): ValidatorBuilder {
+    const { required = false, min, max } = options;
+    const fullField = this._prefix ? `${this._prefix}.${field}` : field;
+
+    if (!this._schema.properties) {
+      this._schema.properties = {};
+    }
+    this._schema.properties[field] = {
+      type: "integer",
+      ...(required && { required: true }),
+      ...(min !== undefined && { minimum: min }),
+      ...(max !== undefined && { maximum: max }),
+    };
+
+    if (required && value == null) {
+      this._errors.push(new ValidationError(`${fullField} is required`));
+    } else if (value != null) {
+      if (!Number.isInteger(value)) {
+        this._errors.push(
+          new ValidationError(`${fullField} must be an integer`),
+        );
+      }
+      if (min !== undefined && value < min) {
+        this._errors.push(
+          new ValidationError(`${fullField} must be at least ${min}`),
+        );
+      }
+      if (max !== undefined && value > max) {
+        this._errors.push(
+          new ValidationError(`${fullField} must be at most ${max}`),
+        );
+      }
+    }
+
+    return this;
+  }
+
+  boolean(
+    field: string,
+    value: boolean | null | undefined,
+    options: {
+      required?: boolean;
+      mustBe?: boolean;
+    } = {},
+  ): ValidatorBuilder {
+    const { required = false, mustBe } = options;
+    const fullField = this._prefix ? `${this._prefix}.${field}` : field;
+
+    if (!this._schema.properties) {
+      this._schema.properties = {};
+    }
+    this._schema.properties[field] = {
+      type: "boolean",
+      ...(required && { required: true }),
+      ...(mustBe !== undefined && { const: mustBe }),
+    };
+
+    if (required && value == null) {
+      this._errors.push(new ValidationError(`${fullField} is required`));
+    } else if (mustBe !== undefined && value !== mustBe) {
+      this._errors.push(new ValidationError(`${fullField} must be ${mustBe}`));
+    }
+
+    return this;
+  }
+
+  array<T>(
+    field: string,
+    value: T[] | null | undefined,
+    options: {
+      required?: boolean;
+      minItems?: number;
+      maxItems?: number;
+      itemType?: string;
+      allowEmpty?: boolean;
+    } = {},
+  ): ValidatorBuilder {
+    const {
+      required = false,
+      minItems,
+      maxItems,
+      itemType = "string",
+      allowEmpty = true,
+    } = options;
+    const fullField = this._prefix ? `${this._prefix}.${field}` : field;
+
+    if (!this._schema.properties) {
+      this._schema.properties = {};
+    }
+    this._schema.properties[field] = {
+      type: "array",
+      ...(required && { required: true }),
+      ...(minItems !== undefined && { minItems }),
+      ...(maxItems !== undefined && { maxItems }),
+      items: { type: itemType as JsonSchemaType },
+    };
+
+    if (required && value == null) {
+      this._errors.push(new ValidationError(`${fullField} is required`));
+    } else if (value != null) {
+      if (!allowEmpty && value.length === 0) {
+        this._errors.push(new ValidationError(`${fullField} cannot be empty`));
+      }
+      if (minItems !== undefined && value.length < minItems) {
+        this._errors.push(
+          new ValidationError(
+            `${fullField} must have at least ${minItems} items`,
+          ),
+        );
+      }
+      if (maxItems !== undefined && value.length > maxItems) {
+        this._errors.push(
+          new ValidationError(
+            `${fullField} must have at most ${maxItems} items`,
+          ),
+        );
+      }
+    }
+
+    return this;
+  }
+
+  enum<T>(
+    field: string,
+    value: T | null | undefined,
+    options: readonly T[],
+    required = false,
+  ): ValidatorBuilder {
+    const fullField = this._prefix ? `${this._prefix}.${field}` : field;
+
+    if (!this._schema.properties) {
+      this._schema.properties = {};
+    }
+    this._schema.properties[field] = {
+      type: "string",
+      enum: options.map(String),
+      ...(required && { required: true }),
+    };
+
+    if (required && value == null) {
+      this._errors.push(new ValidationError(`${fullField} is required`));
+    } else if (value != null && !options.includes(value)) {
+      this._errors.push(
+        new ValidationError(
+          `${fullField} must be one of: ${options.join(", ")}`,
+        ),
+      );
+    }
+
+    return this;
+  }
+
+  dateTime(
+    field: string,
+    value: Date | null | undefined,
+    options: {
+      required?: boolean;
+      pastOrPresent?: boolean;
+      after?: Date;
+      before?: Date;
+    } = {},
+  ): ValidatorBuilder {
+    const { required = false, pastOrPresent = false, after, before } = options;
+    const fullField = this._prefix ? `${this._prefix}.${field}` : field;
+
+    if (!this._schema.properties) {
+      this._schema.properties = {};
+    }
+    this._schema.properties[field] = {
+      type: "string",
+      format: "date-time",
+      ...(required && { required: true }),
+    };
+
+    if (required && value == null) {
+      this._errors.push(new ValidationError(`${fullField} is required`));
+    } else if (value != null) {
+      if (pastOrPresent && value > new Date()) {
+        this._errors.push(
+          new ValidationError(`${fullField} cannot be in the future`),
+        );
+      }
+      if (after && value < after) {
+        this._errors.push(
+          new ValidationError(`${fullField} must be after ${after}`),
+        );
+      }
+      if (before && value > before) {
+        this._errors.push(
+          new ValidationError(`${fullField} must be before ${before}`),
+        );
+      }
+    }
+
+    return this;
+  }
+
+  custom(
+    field: string,
+    validator: () => boolean,
+    errorMessage: string,
+  ): ValidatorBuilder {
+    const fullField = this._prefix ? `${this._prefix}.${field}` : field;
+
+    if (!validator()) {
+      this._errors.push(new ValidationError(`${fullField}: ${errorMessage}`));
+    }
+
+    return this;
+  }
+
+  build(): ValidationResult {
+    if (this._errors.length === 0) {
+      return ValidationResult.success();
+    }
+
+    const fieldErrors: Record<string, string[]> = {};
+    const generalErrors: string[] = [];
+
+    for (const error of this._errors) {
+      const message = error.message;
+      generalErrors.push(message);
+
+      // Extract field name from error message for field-specific grouping
+      // Messages are in format: "fieldName is required" or "fieldName: custom message"
+      const colonIndex = message.indexOf(":");
+      const spaceIndex = message.indexOf(" ");
+
+      let fieldName: string | null = null;
+      let errorMsg = message;
+
+      if (colonIndex !== -1 && (spaceIndex === -1 || colonIndex < spaceIndex)) {
+        // Format: "field: message"
+        fieldName = message.substring(0, colonIndex);
+        errorMsg = message.substring(colonIndex + 1).trim();
+      } else if (spaceIndex !== -1) {
+        // Format: "field message"
+        fieldName = message.substring(0, spaceIndex);
+      }
+
+      if (fieldName) {
+        if (!fieldErrors[fieldName]) {
+          fieldErrors[fieldName] = [];
+        }
+        const errors = fieldErrors[fieldName];
+        if (errors) {
+          errors.push(errorMsg);
+        }
+      }
+    }
+
+    return new ValidationResult(false, generalErrors, fieldErrors);
+  }
+
+  get schema(): JsonSchema {
+    return { ...this._schema } as JsonSchema;
+  }
+}

package/src/index.ts

@@ -0,0 +1,95 @@
+// Core abstractions
+export * from "./common/abstract.entity.ts";
+export { Actor } from "./common/abstract.actor.ts";
+export { Usecase, type UsecaseName } from "./common/abstract.usecase.ts";
+export { type Interceptor } from "./common/abstract.interceptor.ts";
+
+// Interceptors
+export { AuthorizationInterceptor } from "./common/interceptor/authorization.interceptor.ts";
+export { PerformanceInterceptor } from "./common/interceptor/performance.interceptor.ts";
+export {
+  type AuditLogEntry,
+  AuditLogInterceptor,
+  FileAuditLogger,
+} from "./common/interceptor/audit-log.interceptor.ts";
+
+// Types
+export { type JSON } from "./common/type/json.type.ts";
+export {
+  type JsonSchema,
+  type JsonSchemaProperties,
+  type JsonSchemaType,
+} from "./common/type/json-schema.type.ts";
+export { type Metadata } from "./common/type/metadata.type.ts";
+export {
+  type CommonAction,
+  isCommonAction,
+  type Permission,
+  type ResourceConstraints,
+  ResourceScope,
+} from "./common/type/permission.type.ts";
+export {
+  createInterceptorContext,
+  type InterceptorContext,
+} from "./common/type/interceptor-context.type.ts";
+export { type Cents, Money } from "./common/type/money.class.ts";
+export {
+  type Lowercase,
+  type LowercaseArray,
+  type LowercaseArrayUnion,
+} from "./common/type/lowercase.type.ts";
+
+// LLM API Definition
+export {
+  type ApiDefinition,
+  type LlmParameter,
+  type LlmReturnValue,
+} from "./common/llm/api-definition.type.ts";
+
+// Validation
+export { ValidationResult } from "./common/validation/validation-result.ts";
+export {
+  ValidationError,
+  ValidatorBuilder,
+} from "./common/validation/validators.ts";
+
+// Repository
+export { type BaseFilter, Repository } from "./common/abstract.repository.ts";
+
+/**
+ * @deprecated Use Repository instead. Will be removed in v1.0.0
+ */
+export { Repository as BaseRepository } from "./common/abstract.repository.ts";
+
+// Configuration (12-Factor App compliant)
+export {
+  BaseConfigSection,
+  type ConfigSection,
+} from "./common/config/config-section.ts";
+export { ConfigRegistry } from "./common/config/config-registry.ts";
+
+// Patterns
+export {
+  type UnitOfWork,
+  type UnitOfWorkFactory,
+} from "./common/pattern/unit-of-work.ts";
+
+// Exceptions
+export { AuthorizationException } from "./common/exception/authorization-exception.ts";
+export {
+  DatabaseException,
+  EntityAlreadyExistsException,
+  EntityNotFoundException,
+  NetworkException,
+  RepositoryException,
+  ValidationException,
+} from "./common/exception/repository-exception.ts";
+
+// Platform abstraction
+export { getEnv, getEnvOrDefault } from "./common/platform/env.ts";
+
+// Use Case Registry (for auto-discovery systems)
+export {
+  type UseCaseRegistryEntry,
+  UseCaseRegistryHelpers,
+} from "./common/registry/usecase-registry.ts";