bazis 0.96.1

package/library/validation/Validator.ts

@@ -0,0 +1,101 @@
+import { MessageRegistry } from "./MessageRegistry";
+import { RuleEngine } from "./RuleEngine";
+import type { ValidationResult } from "./ValidationResult";
+import { registerFieldRule } from "./metadata";
+import type { ValidatorOptions } from "./types/ValidatorOptions";
+
+/**
+ * Field decorator: registers validation rules in the class metadata.
+ * Uses standard TC39 decorators (run natively by Bun), without
+ * `experimentalDecorators`, `emitDecoratorMetadata` or `reflect-metadata`,
+ * so the module compiles into a binary (`bun build --compile`).
+ */
+type FieldDecorator = (value: undefined, context: ClassFieldDecoratorContext) => void;
+
+function createFieldDecorator(options: ValidatorOptions): FieldDecorator {
+  return (_value, context) => {
+    registerFieldRule(context, options);
+  };
+}
+
+/**
+ * The single entry point of the validation module.
+ *
+ * Both a decorator and a "static class":
+ *
+ * ```ts
+ * class CreateUserDto {
+ *   @Validator({ required: true, minLength: 3, maxLength: 50 })
+ *   username!: string;
+ *
+ *   @Validator({ required: true, email: true })
+ *   email!: string;
+ * }
+ *
+ * const result = Validator.validate(new CreateUserDto());
+ * if (!result.isValid) console.log(result.errors);
+ * ```
+ *
+ * Guarantees:
+ * - class rules are collected and compiled once (WeakMap cache), repeated
+ *   `validate` calls rebuild nothing;
+ * - all errors are collected in one pass; validation does not stop at the first;
+ * - exceptions in `custom`/`validateIf` are caught (code `customError`) and
+ *   validation continues;
+ * - values are read only by the field names declared by decorators; service
+ *   keys (`__proto__` and so on) are never traversed, which protects against
+ *   prototype pollution.
+ */
+export const Validator = Object.assign(
+  /**
+   * `@Validator(options)` goes on a class field. A field may have several
+   * decorators; all of them run.
+   */
+  (options: ValidatorOptions): FieldDecorator => createFieldDecorator(options),
+  {
+    /**
+     * Synchronous validation of an instance.
+     *
+     * Async `custom` functions are not supported here: if a function returns a
+     * Promise, an error with the `asyncCustomInSyncCall` code is added to the
+     * result (use {@link Validator.validateAsync}).
+     *
+     * @param instance Instance of a class with `@Validator` decorators.
+     *   An object without decorators is valid.
+     */
+    validate(instance: object): ValidationResult {
+      return RuleEngine.validate(instance);
+    },
+
+    /**
+     * Asynchronous validation: awaits all async `custom` functions.
+     * Synchronous rules run immediately; the error order is deterministic.
+     */
+    validateAsync(instance: object): Promise<ValidationResult> {
+      return RuleEngine.validateAsync(instance);
+    },
+
+    /**
+     * Globally overrides the standard error messages.
+     * Supported placeholders: `{property}`, `{value}`, `{min}`, `{max}`,
+     * `{pattern}`, `{contains}`, `{allowed}`, `{expected}`, `{actual}`.
+     *
+     * Priority: the decorator's local `message` > the ones set here > built-in.
+     *
+     * ```ts
+     * Validator.setDefaultMessages({
+     *   required: "{property} is required",
+     *   minLength: "At least {min} characters",
+     * });
+     * ```
+     */
+    setDefaultMessages(messages: Partial<Record<string, string>>): void {
+      MessageRegistry.setDefaults(messages);
+    },
+
+    /** Resets global messages to the built-in ones (handy in tests). */
+    resetDefaultMessages(): void {
+      MessageRegistry.reset();
+    },
+  },
+);

package/library/validation/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Class validation module of Bazis.
+ *
+ * Self-contained (Bun APIs only), with no reflection or external dependencies,
+ * compatible with binary compilation (`bun build --compile`).
+ *
+ * The entry point is {@link Validator}: a field decorator plus the static
+ * methods `validate` / `validateAsync` / `setDefaultMessages`.
+ */
+export { Validator } from "./Validator";
+export { modelValidatorAdapter } from "./modelValidatorAdapter";
+export { ValidationError } from "./ValidationError";
+export { ValidationResult } from "./ValidationResult";
+export { MessageRegistry, RU_VALIDATION_MESSAGES, type MessageParams } from "./MessageRegistry";
+export { ValidationCodes, type ValidationCode } from "./types/ValidationCode";
+export type { CustomOutcome, CustomValidator, ValidationTypeHint, ValidatorOptions } from "./types/ValidatorOptions";

package/library/validation/metadata.ts

@@ -0,0 +1,69 @@
+import type { ValidatorOptions } from "./types/ValidatorOptions";
+
+// One-line polyfill: Bun runs standard TC39 decorators natively,
+// but Symbol.metadata may be missing at runtime. Symbol.for gives one shared
+// symbol for all module copies.
+(Symbol as { metadata?: symbol }).metadata ??= Symbol.for("Symbol.metadata");
+
+/** Key under which validation rules are stored in the class metadata. */
+const FIELD_RULES = Symbol.for("bazis:validation:rules");
+
+/** One registered rule: a field + the options of one decorator. */
+export interface FieldRule {
+  readonly property: string;
+  readonly options: ValidatorOptions;
+}
+
+interface RulesMetadata {
+  [FIELD_RULES]?: FieldRule[];
+}
+
+/**
+ * Registers a field rule in the class metadata (called by the decorator).
+ *
+ * TC39 decorator metadata is inherited prototypically: a subclass's metadata
+ * object has the parent's metadata as its prototype. So on the first write to a
+ * concrete class we copy on write: the inherited rules are copied into the
+ * class's own array without mutating the parent's.
+ */
+export function registerFieldRule(context: ClassFieldDecoratorContext, options: ValidatorOptions): void {
+  if (context.static) {
+    throw new Error(`@Validator: static field "${String(context.name)}" is not supported; the decorator works on instance fields only.`);
+  }
+  if (context.private) {
+    throw new Error(`@Validator: private field "${String(context.name)}" is not supported; values are read through ordinary property access.`);
+  }
+
+  const metadata = context.metadata as RulesMetadata;
+  const inherited = metadata[FIELD_RULES];
+  if (!Object.prototype.hasOwnProperty.call(metadata, FIELD_RULES)) {
+    metadata[FIELD_RULES] = inherited ? [...inherited] : [];
+  }
+  metadata[FIELD_RULES]!.push({ property: String(context.name), options });
+}
+
+/**
+ * Returns the validation rules of a class (including inherited ones), or
+ * `undefined` if the class has no `@Validator` decorators.
+ */
+export function rulesOf(ctor: object | undefined | null): readonly FieldRule[] | undefined {
+  if (typeof ctor !== "function") {
+    return undefined;
+  }
+  const metadata = (ctor as unknown as { [key: symbol]: unknown })[Symbol.metadata as unknown as symbol] as
+    | RulesMetadata
+    | undefined;
+  const rules = metadata?.[FIELD_RULES];
+  return rules && rules.length > 0 ? rules : undefined;
+}
+
+/**
+ * Whether the value's class has registered validation rules.
+ * Used to auto-detect `nested`.
+ */
+export function hasRules(value: unknown): boolean {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  return rulesOf((value as object).constructor) !== undefined;
+}

package/library/validation/modelValidatorAdapter.ts

@@ -0,0 +1,119 @@
+import { Validator } from "./Validator";
+import { rulesOf } from "./metadata";
+
+interface AdapterValidationIssue {
+  readonly property: string;
+  readonly message: string;
+  readonly code?: string;
+}
+
+/**
+ * Pure adapter of the validation library to the structural request-model
+ * validator contract. It deliberately **does not import the kernel**: it returns
+ * an object of the shape `{ validate(instance) => { isValid, errors } }`, which is
+ * structurally compatible with the `ModelValidator` port from `bazis/core/http`.
+ *
+ * `runApp` plugs it in by default (unless `options.validator` is given). Outside
+ * `runApp`, for example in a test, wire it yourself:
+ *
+ * ```ts
+ * import { useModelValidator } from "bazis/core/http";
+ * import { modelValidatorAdapter } from "bazis/library/validation";
+ *
+ * useModelValidator(modelValidatorAdapter);
+ * ```
+ *
+ * This keeps the library independent of the kernel and the runtime, and the
+ * kernel unaware of the concrete validation engine (dependency inversion).
+ */
+export const modelValidatorAdapter = {
+  validate(instance: object): {
+    readonly isValid: boolean;
+    readonly errors: readonly { readonly property: string; readonly message: string; readonly code?: string }[];
+  } {
+    const result = Validator.validate(instance);
+    const nestedInstanceErrors = validateExplicitNestedInstances(instance);
+    const errors: AdapterValidationIssue[] = result.errors.map((error) => ({
+      property: error.property,
+      message: error.message,
+      code: error.code,
+    }));
+    errors.push(...nestedInstanceErrors);
+    return {
+      isValid: errors.length === 0,
+      errors,
+    };
+  },
+};
+
+/**
+ * `nested: true` must never silently validate a plain object with no class
+ * metadata. Generated HTTP hydration normally makes every value a DTO
+ * instance; this adapter check is the fail-closed guard for stale/missing
+ * generated metadata and DTO integrations.
+ */
+function validateExplicitNestedInstances(root: object): AdapterValidationIssue[] {
+  const errors: AdapterValidationIssue[] = [];
+  inspectExplicitNested(root, "", errors, new Set<object>());
+  return errors;
+}
+
+function inspectExplicitNested(
+  instance: object,
+  prefix: string,
+  errors: AdapterValidationIssue[],
+  seen: Set<object>,
+): void {
+  if (seen.has(instance)) {
+    return;
+  }
+  seen.add(instance);
+  const rules = rulesOf(instance.constructor);
+  if (rules === undefined) {
+    return;
+  }
+  const explicitProperties = new Set<string>();
+  for (const rule of rules) {
+    if (rule.options.nested === true) {
+      explicitProperties.add(rule.property);
+    }
+  }
+  for (const property of explicitProperties) {
+    const value = (instance as Record<string, unknown>)[property];
+    if (value === undefined || value === null) {
+      continue;
+    }
+    const path = prefix === "" ? property : `${prefix}.${property}`;
+    if (Array.isArray(value)) {
+      for (let index = 0; index < value.length; index += 1) {
+        inspectNestedValue(value[index], `${path}[${index}]`, errors, seen);
+      }
+    } else {
+      inspectNestedValue(value, path, errors, seen);
+    }
+  }
+}
+
+function inspectNestedValue(
+  value: unknown,
+  path: string,
+  errors: AdapterValidationIssue[],
+  seen: Set<object>,
+): void {
+  // Validation's established optional/null semantics also apply to nullable
+  // array elements; `required` on the owning field handles the field itself.
+  if (value === null) {
+    return;
+  }
+  const prototype = typeof value === "object" ? Object.getPrototypeOf(value) as { constructor?: unknown } | null : null;
+  const constructor = prototype?.constructor;
+  if (typeof value !== "object" || typeof constructor !== "function" || rulesOf(constructor) === undefined) {
+    errors.push({
+      property: path,
+      message: `Field "${path}" must be a hydrated DTO instance`,
+      code: "nestedModel",
+    });
+    return;
+  }
+  inspectExplicitNested(value, path, errors, seen);
+}

package/library/validation/types/ValidationCode.ts

@@ -0,0 +1,69 @@
+/**
+ * Validation error codes.
+ *
+ * A code uniquely identifies the rule that failed. The message template is
+ * picked by code: the decorator's local `message` > global
+ * (`Validator.setDefaultMessages`) > the built-in default.
+ */
+export const ValidationCodes = {
+  /** The value is missing (`undefined` or `null`) but the field is required. */
+  required: "required",
+  /** The string is empty but the rule requires a non-empty one. */
+  notEmpty: "notEmpty",
+  /** The string is shorter than the minimum. */
+  minLength: "minLength",
+  /** The string is longer than the maximum. */
+  maxLength: "maxLength",
+  /** The string length is outside `length: [min, max]`. */
+  length: "length",
+  /** The string does not contain the required substring. */
+  contains: "contains",
+  /** The string contains a forbidden substring. */
+  notContains: "notContains",
+  /** The string does not match the regular expression. */
+  pattern: "pattern",
+  /** The string is not a valid email address. */
+  email: "email",
+  /** The string is not a valid URL. */
+  url: "url",
+  /** The string is not a valid UUID. */
+  uuid: "uuid",
+  /** The value has the wrong type (see `{expected}` / `{actual}`). */
+  type: "type",
+  /** The number is below the minimum. */
+  min: "min",
+  /** The number is above the maximum. */
+  max: "max",
+  /** The number is outside `range: [min, max]`. */
+  range: "range",
+  /** The number is not positive. */
+  positive: "positive",
+  /** The number is not negative. */
+  negative: "negative",
+  /** The number is not an integer. */
+  integer: "integer",
+  /** The boolean value is not `true`. */
+  mustBeTrue: "mustBeTrue",
+  /** The boolean value is not `false`. */
+  mustBeFalse: "mustBeFalse",
+  /** The value is not in the `enumType` enumeration. */
+  enum: "enum",
+  /** The string does not parse as JSON. */
+  json: "json",
+  /** The string is not a valid phone number. */
+  phone: "phone",
+  /** The value is not a valid date. */
+  date: "date",
+  /** The `custom` check returned `false` or a string. */
+  custom: "custom",
+  /** The `custom` check (or `validateIf`) threw an exception. */
+  customError: "customError",
+  /**
+   * An async `custom` check was called through the synchronous `validate()`.
+   * Use `Validator.validateAsync()`.
+   */
+  asyncCustomInSyncCall: "asyncCustomInSyncCall",
+} as const;
+
+/** Union type of all built-in error codes. */
+export type ValidationCode = (typeof ValidationCodes)[keyof typeof ValidationCodes];

package/library/validation/types/ValidatorOptions.ts

@@ -0,0 +1,153 @@
+import type { ValidationError } from "../ValidationError";
+
+/**
+ * Hint about the field value type.
+ *
+ * Optional: the module works without reflection (`emitDecoratorMetadata` and
+ * `reflect-metadata` are not used; they conflict with the "no external
+ * dependencies" principle), so the expected type is either set explicitly or
+ * inferred from the rules themselves (`minLength` implies a string, `min` a
+ * number and so on).
+ */
+export type ValidationTypeHint =
+  | "string"
+  | "number"
+  | "boolean"
+  | "enum"
+  | "json"
+  | "phone"
+  | "email"
+  | "date"
+  | "any";
+
+/**
+ * Result of a `custom` check:
+ * - `true` or `void`: the value is valid;
+ * - `false`: an error with the standard message (code `custom`);
+ * - `string`: an error with this message (code `custom`);
+ * - `ValidationError`: added to the result as is.
+ */
+export type CustomOutcome = boolean | string | void | ValidationError;
+
+/**
+ * Custom check. May be synchronous or asynchronous (async checks run only
+ * through `Validator.validateAsync`).
+ *
+ * @param value Current field value.
+ * @param instance The whole instance being checked, for cross-field checks
+ *   such as "if field A equals X, field B is required".
+ */
+export type CustomValidator = (value: unknown, instance: unknown) => CustomOutcome | Promise<CustomOutcome>;
+
+/**
+ * The rule set of one `@Validator(...)` decorator.
+ *
+ * A field may have several decorators; all of them run. Rules inside one
+ * decorator are checked in a fixed order: `validateIf` -> `required` -> the
+ * `type` hint -> string/number/boolean/enum/date rules -> `custom` -> `nested`.
+ */
+export interface ValidatorOptions {
+  /** Explicit value type hint. See {@link ValidationTypeHint}. */
+  type?: ValidationTypeHint;
+
+  // ── General ──────────────────────────────────────────────────────────────
+
+  /** The value is required: `undefined` and `null` are errors (code `required`). */
+  required?: boolean;
+
+  /**
+   * Conditional validation: if the function returns `false`, all other rules of
+   * this decorator are skipped. It gets the whole instance, so it can rely on
+   * the values of other fields.
+   */
+  validateIf?: (instance: never) => boolean;
+
+  /**
+   * Custom check (synchronous or asynchronous).
+   * An exception inside the function is caught and turned into a
+   * `ValidationError` with the `customError` code; validation continues.
+   */
+  custom?: CustomValidator;
+
+  /**
+   * Local error message for all rules of this decorator.
+   * Has the highest priority (above `Validator.setDefaultMessages`).
+   * Supports placeholders: `{property}`, `{value}`, `{min}`, `{max}`,
+   * `{pattern}`, `{contains}`, `{allowed}`, `{expected}`, `{actual}`.
+   */
+  message?: string;
+
+  /**
+   * Recursive check of the value as a class with `@Validator` decorators.
+   * If not set, it turns on automatically when the field value is an instance
+   * of a class with registered rules. `nested: false` turns off the auto mode.
+   * Arrays are checked element by element (`items[0].name`); circular
+   * references are safely skipped.
+   */
+  nested?: boolean;
+
+  // ── Strings ──────────────────────────────────────────────────────────────
+
+  /** The string must not be empty (`""`). */
+  notEmpty?: boolean;
+  /** Minimum string length (inclusive). */
+  minLength?: number;
+  /** Maximum string length (inclusive); exceeding it skips this decorator's content checks. */
+  maxLength?: number;
+  /** String length range `[min, max]` (inclusive); exceeding max skips this decorator's content checks. */
+  length?: readonly [number, number];
+  /** The string must contain the substring. */
+  contains?: string;
+  /** The string must not contain the substring. */
+  notContains?: string;
+  /**
+   * Regular expression (a RegExp or a source string).
+   * Compiled once on the first access to the class and cached.
+   * For untrusted input set maxLength/length in the same decorator.
+   */
+  pattern?: RegExp | string;
+  /** The string must be a valid email address. */
+  email?: boolean;
+  /** The string must be a valid URL (checked with `URL.canParse`). */
+  url?: boolean;
+  /**
+   * The string must be a valid UUID (versions 1–8, including v4 from
+   * `crypto.randomUUID()` and v7 from `Bun.randomUUIDv7()`; the nil UUID is allowed).
+   */
+  uuid?: boolean;
+  /** The string must parse as JSON. */
+  json?: boolean;
+  /** The string must be a phone number: an optional `+`, 7–15 digits; spaces, hyphens and parentheses are allowed. */
+  phone?: boolean;
+
+  // ── Numbers ──────────────────────────────────────────────────────────────
+
+  /** The number is not less than this value. */
+  min?: number;
+  /** The number is not greater than this value. */
+  max?: number;
+  /** The number is in the `[min, max]` range (inclusive). */
+  range?: readonly [number, number];
+  /** The number is strictly greater than zero. */
+  positive?: boolean;
+  /** The number is strictly less than zero. */
+  negative?: boolean;
+  /** The number must be an integer. */
+  integer?: boolean;
+
+  // ── Boolean ──────────────────────────────────────────────────────────────
+
+  /** The value must be exactly `true` (for example, accepting terms). */
+  mustBeTrue?: boolean;
+  /** The value must be exactly `false`. */
+  mustBeFalse?: boolean;
+
+  // ── Enum ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Enum object whose values must include the field value.
+   * TypeScript string and numeric enums are supported (reverse keys of numeric
+   * enums are ignored).
+   */
+  enumType?: Record<string, string | number>;
+}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "bazis",
+  "version": "0.96.1",
+  "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
+  "license": "MIT",
+  "author": "Alexander Alenin",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asus97178/bazis.git",
+    "directory": "src/bazis"
+  },
+  "homepage": "https://github.com/asus97178/bazis/tree/main/src/bazis#readme",
+  "bugs": {
+    "url": "https://github.com/asus97178/bazis/issues"
+  },
+  "keywords": [
+    "bun",
+    "typescript",
+    "framework",
+    "dependency-injection",
+    "orm",
+    "postgresql",
+    "http",
+    "websocket",
+    "codegen"
+  ],
+  "type": "module",
+  "module": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./core/agent": "./core/agent/index.ts",
+    "./core/app": "./core/app/index.ts",
+    "./core/background": "./core/background/index.ts",
+    "./core/cache": "./core/cache/index.ts",
+    "./core/di": "./core/di/index.ts",
+    "./core/generatedRuntime": "./core/generatedRuntime.ts",
+    "./core/grpc": "./core/grpc/index.ts",
+    "./core/http": "./core/http/index.ts",
+    "./core/http-client": "./core/http-client/index.ts",
+    "./core/http/OpenApi/generatedOpenApiRegistry": "./core/http/OpenApi/generatedOpenApiRegistry.ts",
+    "./core/infra": "./core/infra/index.ts",
+    "./core/kernel": "./core/kernel/index.ts",
+    "./core/orm": "./core/orm/index.ts",
+    "./core/websocket": "./core/websocket/index.ts",
+    "./library/boundary": "./library/boundary/index.ts",
+    "./library/http-client": "./library/http-client/index.ts",
+    "./library/jsonapi": "./library/jsonapi/index.ts",
+    "./library/jwt": "./library/jwt/index.ts",
+    "./library/openapi": "./library/openapi/index.ts",
+    "./library/orm": "./library/orm/index.ts",
+    "./library/redaction": "./library/redaction/index.ts",
+    "./library/ui": "./library/ui/index.ts",
+    "./library/validation": "./library/validation/index.ts"
+  },
+  "bin": {
+    "bazis": "./cli/main.ts"
+  },
+  "files": [
+    "index.ts",
+    "core",
+    "library",
+    "cli",
+    "README.md",
+    "LICENSE",
+    "!**/test",
+    "!**/*.test.ts",
+    "!**/*.spec.ts",
+    "!**/MODULE.md"
+  ],
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}