bazis 0.96.1

package/library/ui/uiProfileAuthoring.ts

@@ -0,0 +1,289 @@
+/**
+ * Process-local authoring contracts for `@UiProfile()`.
+ *
+ * These declarations deliberately keep controller and request-model class
+ * references. They are application metadata, not the JSON wire contract. A
+ * higher layer may resolve them against HTTP/OpenAPI metadata and only then
+ * produce a serializable `UiProfileV1`.
+ */
+
+export type UiAuthoringClass<T = object> = abstract new (...args: any[]) => T;
+export type UiControllerClass<T = object> = UiAuthoringClass<T>;
+export type UiRequestClass<T = object> = UiAuthoringClass<T>;
+
+export type UiControllerMethodKey<Controller extends UiControllerClass> = {
+  [Key in keyof InstanceType<Controller>]-?: InstanceType<Controller>[Key] extends
+    (...args: any[]) => unknown
+    ? Key
+    : never;
+}[keyof InstanceType<Controller>] & string;
+
+export type UiControllerMethod<Controller extends UiControllerClass> =
+  InstanceType<Controller>[UiControllerMethodKey<Controller>] & ((...args: any[]) => unknown);
+
+export type UiDataFieldKey<Model> = unknown extends Model
+  ? string
+  : {
+      [Key in keyof Model]-?: Model[Key] extends (...args: any[]) => unknown
+        ? never
+        : Key;
+    }[keyof Model] & string;
+
+export type UiResponseReference<Response = unknown> = UiAuthoringClass<Response>;
+
+export type UiResponseValue<Reference> = Reference extends UiAuthoringClass<infer Response>
+  ? Response
+  : unknown;
+
+export type UiRequestValue<Reference> = Reference extends UiRequestClass<infer Request>
+  ? Request
+  : unknown;
+
+export interface UiControllerMethodReference<Controller extends UiControllerClass = UiControllerClass> {
+  readonly kind: "ui-controller-method";
+  readonly controller: Controller;
+  readonly action: UiControllerMethod<Controller>;
+}
+
+/** Captures exact controller-action identity for an explicit CRUD operation. */
+export function uiOperation<Controller extends UiControllerClass>(
+  controller: Controller,
+  action: UiControllerMethod<Controller>,
+): UiControllerMethodReference<Controller> {
+  return Object.freeze({
+    kind: "ui-controller-method",
+    controller,
+    action,
+  });
+}
+
+export interface UiEndpointAuthoringOptions<
+  Request extends UiRequestClass | undefined = undefined,
+  Response extends UiResponseReference | undefined = undefined,
+> {
+  readonly request?: Request;
+  readonly response?: Response;
+}
+
+export interface UiEndpointReference<
+  Controller extends UiControllerClass = UiControllerClass,
+  Request extends UiRequestClass | undefined = UiRequestClass | undefined,
+  Response extends UiResponseReference | undefined = UiResponseReference | undefined,
+> {
+  readonly kind: "ui-endpoint";
+  readonly controller: Controller;
+  readonly action: UiControllerMethod<Controller>;
+  readonly request?: Request;
+  readonly response?: Response;
+}
+
+/**
+ * Captures exact controller-action identity plus optional nominal request and
+ * response assertions.
+ */
+export function uiEndpoint<
+  Controller extends UiControllerClass,
+  Request extends UiRequestClass | undefined = undefined,
+  Response extends UiResponseReference | undefined = undefined,
+>(
+  controller: Controller,
+  action: UiControllerMethod<Controller>,
+  assertions?: UiEndpointAuthoringOptions<Request, Response>,
+): UiEndpointReference<Controller, Request, Response>;
+export function uiEndpoint<
+  Controller extends UiControllerClass,
+  Request extends UiRequestClass | undefined = undefined,
+  Response extends UiResponseReference | undefined = undefined,
+>(
+  controller: Controller,
+  action: UiControllerMethod<Controller>,
+  assertions: UiEndpointAuthoringOptions<Request, Response> = {},
+): UiEndpointReference<Controller, Request, Response> {
+  return Object.freeze({
+    kind: "ui-endpoint",
+    controller,
+    action,
+    ...(assertions.request !== undefined ? { request: assertions.request } : {}),
+    ...(assertions.response !== undefined ? { response: assertions.response } : {}),
+  });
+}
+
+export interface UiProfileOperations<Controller extends UiControllerClass> {
+  readonly list?: UiControllerMethodReference<Controller>;
+  readonly read?: UiControllerMethodReference<Controller>;
+  readonly create?: UiControllerMethodReference<Controller>;
+  readonly update?: UiControllerMethodReference<Controller>;
+  readonly delete?: UiControllerMethodReference<Controller>;
+}
+
+export interface UiProfileNavigationOverride {
+  readonly title?: string;
+  readonly group?: string;
+  readonly icon?: string;
+  readonly order?: number;
+  readonly hidden?: boolean;
+}
+
+export interface UiListFieldOverride {
+  readonly hidden?: boolean;
+}
+
+export interface UiFormFieldOverride {
+  readonly label?: string;
+  readonly hidden?: boolean;
+  readonly options?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Typed field selection keyed by real response/request properties.
+ */
+export type UiFieldSelection<Model = unknown> = Partial<Readonly<Record<
+  UiDataFieldKey<Model>,
+  UiListFieldOverride
+>>>;
+
+export type UiFormFieldMap<Model = unknown> = Partial<Readonly<Record<
+  UiDataFieldKey<Model>,
+  UiFormFieldOverride
+>>>;
+
+export type UiSortField<Model> =
+  | UiDataFieldKey<Model>
+  | `-${UiDataFieldKey<Model>}`;
+
+export interface UiListAuthoringOverride<
+  Response = unknown,
+  Request extends UiRequestClass | undefined = undefined,
+> {
+  /** Optional direct list-request contract; filters/sort are typed from it. */
+  readonly request?: Request;
+  readonly title?: string;
+  readonly columns?: UiFieldSelection<Response>;
+  readonly filters?: UiFieldSelection<UiRequestValue<Request>>;
+  readonly defaultSort?: UiSortField<UiRequestValue<Request>>;
+  readonly pageSize?: number;
+}
+
+export interface UiFormAuthoringOverride<
+  Request extends UiRequestClass | undefined = undefined,
+> {
+  /** Direct request contract; validation facts remain owned by this class. */
+  readonly request?: Request;
+  readonly title?: string;
+  readonly fields?: UiFormFieldMap<UiRequestValue<Request>>;
+}
+
+export type UiActionIntentOverride = "primary" | "secondary" | "danger" | "neutral";
+
+export type UiActionPlacementOverride =
+  | "list.header"
+  | "list.row"
+  | "detail.header";
+
+export interface UiDeleteAuthoringOverride {
+  readonly title?: string;
+  readonly intent?: UiActionIntentOverride;
+  readonly confirm?: string;
+  readonly placements?: readonly UiActionPlacementOverride[];
+  readonly refresh?: "none" | "resource" | "page" | "all";
+  readonly hidden?: boolean;
+}
+
+export interface UiCustomPageBaseAuthoring {
+  readonly id: string;
+  readonly title: string;
+  readonly navigation?: UiProfileNavigationOverride;
+}
+
+export interface UiSettingsPageAuthoring extends UiCustomPageBaseAuthoring {
+  readonly kind: "settings";
+  readonly read: UiEndpointReference;
+  readonly update: UiEndpointReference;
+  readonly form?: {
+    readonly title?: string;
+    readonly fields?: UiFormFieldMap<any>;
+  };
+}
+
+export interface UiDocumentPageAuthoring extends UiCustomPageBaseAuthoring {
+  readonly kind: "document";
+  readonly load: UiEndpointReference;
+}
+
+export interface UiDashboardBlockAuthoring {
+  readonly id: string;
+  readonly kind: "metric" | "document";
+  readonly title: string;
+  readonly load: UiEndpointReference;
+}
+
+export interface UiDashboardPageAuthoring extends UiCustomPageBaseAuthoring {
+  readonly kind: "dashboard";
+  readonly blocks: readonly UiDashboardBlockAuthoring[];
+}
+
+/** Feature-owned client page. Transport remains outside the UI profile. */
+export interface UiFeaturePageAuthoring extends UiCustomPageBaseAuthoring {
+  readonly kind: "feature";
+  readonly renderer: string;
+}
+
+export type UiCustomPageAuthoring =
+  | UiSettingsPageAuthoring
+  | UiDocumentPageAuthoring
+  | UiDashboardPageAuthoring
+  | UiFeaturePageAuthoring;
+
+/** Page-only profile; feature modules keep one local profile per owner. */
+export interface UiCustomPagesProfileAuthoringOptions {
+  readonly surface: string;
+  readonly customPages: readonly UiCustomPageAuthoring[];
+}
+
+/**
+ * Application-facing UI profile. Everything except the process-local source
+ * references is presentation intent; transport, validation and authorization
+ * remain owned by HTTP/OpenAPI/policy layers.
+ */
+export interface UiProfileAuthoringOptions<
+  Controller extends UiControllerClass = UiControllerClass,
+  Response extends UiResponseReference | undefined = undefined,
+  ListRequest extends UiRequestClass | undefined = undefined,
+  CreateRequest extends UiRequestClass | undefined = undefined,
+  EditRequest extends UiRequestClass | undefined = undefined,
+> {
+  readonly surface: string;
+  readonly controller: Controller;
+  readonly response?: Response;
+  /** Stable UI resource id; inferred from a simple controller prefix when omitted. */
+  readonly id?: string;
+  readonly title?: string;
+  readonly singularTitle?: string;
+  readonly navigation?: UiProfileNavigationOverride;
+  readonly readonly?: boolean;
+  /** Advanced overrides keyed by semantic operation name. */
+  readonly operations?: UiProfileOperations<Controller>;
+  readonly list?: UiListAuthoringOverride<UiResponseValue<Response>, ListRequest>;
+  readonly create?: UiFormAuthoringOverride<CreateRequest>;
+  readonly edit?: UiFormAuthoringOverride<EditRequest>;
+  readonly delete?: UiDeleteAuthoringOverride;
+}
+
+/** Broad runtime form used only by metadata readers. */
+/** Broad metadata-reader shape; decorator overloads retain strict authoring types. */
+export interface AnyUiProfileAuthoringOptions {
+  readonly surface: string;
+  readonly controller?: UiControllerClass;
+  readonly response?: UiResponseReference;
+  readonly id?: string;
+  readonly title?: string;
+  readonly singularTitle?: string;
+  readonly navigation?: UiProfileNavigationOverride;
+  readonly readonly?: boolean;
+  readonly operations?: UiProfileOperations<any>;
+  readonly list?: UiListAuthoringOverride<any, any>;
+  readonly create?: UiFormAuthoringOverride<any>;
+  readonly edit?: UiFormAuthoringOverride<any>;
+  readonly delete?: UiDeleteAuthoringOverride;
+  readonly customPages?: readonly UiCustomPageAuthoring[];
+}

package/library/ui/uiProfileAuthoringMetadata.ts

@@ -0,0 +1,78 @@
+import type { AnyUiProfileAuthoringOptions } from "./uiProfileAuthoring";
+
+// Bun executes TC39 decorators natively, but Symbol.metadata may be absent.
+(Symbol as { metadata?: symbol }).metadata ??= Symbol.for("Symbol.metadata");
+
+const UI_PROFILE_AUTHORING_META = Symbol.for("bazis:ui-profile:authoring");
+
+export interface UiProfileAuthoringMetadata {
+  readonly target: object;
+  readonly targetName: string;
+  /** The original process-local authoring object, preserved by identity. */
+  readonly profile: AnyUiProfileAuthoringOptions;
+}
+
+interface UiProfileAuthoringCarrier {
+  [UI_PROFILE_AUTHORING_META]?: UiProfileAuthoringMetadata;
+}
+
+interface NamedConstructor {
+  readonly name?: string;
+}
+
+function classNameOf(target: object): string {
+  return (target as NamedConstructor).name?.trim() || "<anonymous UI profile>";
+}
+
+function readCarrier(ctor: object): UiProfileAuthoringCarrier | undefined {
+  return (ctor as { [key: symbol]: unknown })[Symbol.metadata as unknown as symbol] as
+    | UiProfileAuthoringCarrier
+    | undefined;
+}
+
+export function defineUiProfileAuthoringMetadata(
+  target: object,
+  metadata: object,
+  profile: AnyUiProfileAuthoringOptions,
+): void {
+  freezeAuthoringValue(profile, new WeakSet<object>());
+  (metadata as UiProfileAuthoringCarrier)[UI_PROFILE_AUTHORING_META] = Object.freeze({
+    target,
+    targetName: classNameOf(target),
+    profile,
+  });
+}
+
+function freezeAuthoringValue(value: unknown, seen: WeakSet<object>): void {
+  if (value === null || typeof value !== "object" || seen.has(value)) {
+    return;
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      freezeAuthoringValue(item, seen);
+    }
+    Object.freeze(value);
+    return;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    return;
+  }
+  for (const item of Object.values(value as Readonly<Record<string, unknown>>)) {
+    freezeAuthoringValue(item, seen);
+  }
+  Object.freeze(value);
+}
+
+export function uiProfileAuthoringMetadataOf(ctor: object): UiProfileAuthoringMetadata | undefined {
+  const metadata = readCarrier(ctor);
+  if (!metadata || !Object.prototype.hasOwnProperty.call(metadata, UI_PROFILE_AUTHORING_META)) {
+    return undefined;
+  }
+  return metadata[UI_PROFILE_AUTHORING_META];
+}
+
+export function isUiProfileAuthoringClass(value: unknown): value is object {
+  return typeof value === "function" && uiProfileAuthoringMetadataOf(value) !== undefined;
+}

package/library/validation/MessageRegistry.ts

@@ -0,0 +1,144 @@
+/**
+ * Parameters substituted into message placeholders.
+ * The key is the placeholder name without braces: `{min}` -> `min`.
+ */
+export type MessageParams = Readonly<Record<string, unknown>>;
+
+/** Built-in default messages (English). */
+const BUILT_IN: Readonly<Record<string, string>> = {
+  required: 'Field "{property}" is required',
+  notEmpty: 'Field "{property}" must not be empty',
+  minLength: 'Field "{property}" must be at least {min} characters long',
+  maxLength: 'Field "{property}" must be at most {max} characters long',
+  length: 'Field "{property}" must be {min} to {max} characters long',
+  contains: 'Field "{property}" must contain "{contains}"',
+  notContains: 'Field "{property}" must not contain "{contains}"',
+  pattern: 'Field "{property}" does not match the format {pattern}',
+  email: 'Field "{property}" must be a valid email address',
+  url: 'Field "{property}" must be a valid URL',
+  uuid: 'Field "{property}" must be a valid UUID',
+  type: 'Field "{property}" must be of type {expected}, got: {actual}',
+  min: 'Field "{property}" must be at least {min}',
+  max: 'Field "{property}" must be at most {max}',
+  range: 'Field "{property}" must be between {min} and {max}',
+  positive: 'Field "{property}" must be a positive number',
+  negative: 'Field "{property}" must be a negative number',
+  integer: 'Field "{property}" must be an integer',
+  mustBeTrue: 'Field "{property}" must be true',
+  mustBeFalse: 'Field "{property}" must be false',
+  enum: 'Field "{property}" must be one of: {allowed}',
+  json: 'Field "{property}" must be a valid JSON string',
+  phone: 'Field "{property}" must be a valid phone number',
+  date: 'Field "{property}" must be a valid date',
+  custom: 'Field "{property}" failed a custom check',
+  customError: 'Check of field "{property}" failed with an error: {error}',
+  asyncCustomInSyncCall:
+    'Field "{property}": an async custom check is not supported by synchronous validate(); use validateAsync()',
+};
+
+/**
+ * Russian texts for every built-in code. Apply once at startup:
+ * `MessageRegistry.setDefaults(RU_VALIDATION_MESSAGES)`.
+ */
+export const RU_VALIDATION_MESSAGES: Readonly<Record<string, string>> = Object.freeze({
+  required: 'Поле "{property}" обязательно для заполнения',
+  notEmpty: 'Поле "{property}" не должно быть пустым',
+  minLength: 'Поле "{property}" должно содержать не менее {min} символов',
+  maxLength: 'Поле "{property}" должно содержать не более {max} символов',
+  length: 'Поле "{property}" должно содержать от {min} до {max} символов',
+  contains: 'Поле "{property}" должно содержать "{contains}"',
+  notContains: 'Поле "{property}" не должно содержать "{contains}"',
+  pattern: 'Поле "{property}" не соответствует формату {pattern}',
+  email: 'Поле "{property}" должно быть корректным email-адресом',
+  url: 'Поле "{property}" должно быть корректным URL',
+  uuid: 'Поле "{property}" должно быть корректным UUID',
+  type: 'Поле "{property}" должно иметь тип {expected}, получено: {actual}',
+  min: 'Поле "{property}" должно быть не меньше {min}',
+  max: 'Поле "{property}" должно быть не больше {max}',
+  range: 'Поле "{property}" должно быть в диапазоне от {min} до {max}',
+  positive: 'Поле "{property}" должно быть положительным числом',
+  negative: 'Поле "{property}" должно быть отрицательным числом',
+  integer: 'Поле "{property}" должно быть целым числом',
+  mustBeTrue: 'Поле "{property}" должно быть равно true',
+  mustBeFalse: 'Поле "{property}" должно быть равно false',
+  enum: 'Поле "{property}" должно быть одним из: {allowed}',
+  json: 'Поле "{property}" должно быть корректной JSON-строкой',
+  phone: 'Поле "{property}" должно быть корректным номером телефона',
+  date: 'Поле "{property}" должно быть корректной датой',
+  custom: 'Поле "{property}" не прошло пользовательскую проверку',
+  customError: 'Проверка поля "{property}" завершилась ошибкой: {error}',
+  asyncCustomInSyncCall:
+    'Поле "{property}": асинхронная custom-проверка не поддерживается синхронным validate(), используйте validateAsync()',
+});
+
+/**
+ * Registry of error message templates.
+ *
+ * Template priority: the decorator's local `message` > global (`setDefaults`)
+ * > built-in. `{name}` placeholders are replaced with values from the error
+ * parameters; unknown placeholders stay as is (no exceptions: resilience
+ * matters more than strictness here).
+ */
+export class MessageRegistry {
+  /** Current global templates: a copy of the built-in ones + overrides. */
+  private static defaults: Record<string, string> = { ...BUILT_IN };
+
+  /**
+   * Overrides global messages for error codes.
+   * Unknown codes are accepted too, so messages can be set for custom codes
+   * from `custom` functions.
+   */
+  static setDefaults(messages: Partial<Record<string, string>>): void {
+    for (const code of Object.keys(messages)) {
+      // hasOwnProperty: protection against prototype pollution through the given object.
+      if (!Object.prototype.hasOwnProperty.call(messages, code)) {
+        continue;
+      }
+      const template = messages[code];
+      if (typeof template === "string") {
+        MessageRegistry.defaults[code] = template;
+      }
+    }
+  }
+
+  /** Resets all global overrides to the built-in messages. */
+  static reset(): void {
+    MessageRegistry.defaults = { ...BUILT_IN };
+  }
+
+  /**
+   * Builds the final message for an error code.
+   *
+   * @param code Rule code (for example `minLength`).
+   * @param localMessage Local `message` from the decorator options (takes priority).
+   * @param params Placeholder values.
+   */
+  static format(code: string, localMessage: string | undefined, params: MessageParams): string {
+    const template =
+      localMessage ??
+      (Object.prototype.hasOwnProperty.call(MessageRegistry.defaults, code)
+        ? MessageRegistry.defaults[code]!
+        : 'Поле "{property}" не прошло проверку ({code})');
+    return MessageRegistry.interpolate(template, params);
+  }
+
+  private static interpolate(template: string, params: MessageParams): string {
+    return template.replace(/\{(\w+)\}/g, (placeholder, key: string) => {
+      if (!Object.prototype.hasOwnProperty.call(params, key) || params[key] === undefined) {
+        return placeholder;
+      }
+      return MessageRegistry.stringify(params[key]);
+    });
+  }
+
+  private static stringify(value: unknown): string {
+    if (typeof value === "object" && value !== null && !(value instanceof RegExp)) {
+      try {
+        return JSON.stringify(value);
+      } catch {
+        return String(value);
+      }
+    }
+    return String(value);
+  }
+}

package/library/validation/README.md

@@ -0,0 +1,62 @@
+# src/bazis/library/validation: class validation module
+
+A self-contained OOP-style validation module: one `@Validator(options)` decorator
+on class fields + the static `Validator.validate` / `Validator.validateAsync`.
+
+The full specification (every scenario with examples, the options, error codes,
+placeholders) is in [SPEC.md](SPEC.md).
+
+Principles (shared by the whole framework):
+
+- no external dependencies, only Bun APIs;
+- no reflection: standard TC39 decorators + `Symbol.metadata`
+  (no `experimentalDecorators`, `emitDecoratorMetadata` or `reflect-metadata`);
+- compatible with `bun build --compile`;
+- few allocations: a class's validation plan is compiled once and cached in a
+  WeakMap, message objects are created only on the error path;
+- resilience: exceptions in `custom`/`validateIf` are caught
+  (code `customError`), and validation continues and collects all errors.
+
+## Quick start
+
+```ts
+import { Validator } from "@/library/validation";
+
+class CreateUserDto {
+  @Validator({ required: true, minLength: 3, maxLength: 50 })
+  username!: string;
+
+  @Validator({ required: true, email: true })
+  email!: string;
+}
+
+const result = Validator.validate(dto);      // ValidationResult
+await Validator.validateAsync(dto);           // awaits async custom functions
+Validator.setDefaultMessages({ required: "{property} is required" });
+```
+
+More scenarios (complex conditions, async, nested objects) are in
+[test/validation.test.ts](test/validation.test.ts).
+
+## Folder map
+
+| File | Purpose |
+|---|---|
+| `Validator.ts` | public facade: the decorator + `validate`/`validateAsync`/`setDefaultMessages` |
+| `ValidationError.ts` | one error: `property`, `value`, `message`, `code` |
+| `ValidationResult.ts` | the outcome: `isValid`, `errors`, `getErrorsFor`, `hasErrorsFor` |
+| `RuleEngine.ts` | the engine: one pass over the plan, sync/async, nested, cycle protection |
+| `RuleCompiler.ts` | compiles class rules into a plan + WeakMap cache (RegExp, enum Set) |
+| `MessageRegistry.ts` | message templates, placeholders, priority local > global > built-in; built-in texts are English, `RU_VALIDATION_MESSAGES` is a Russian set for `setDefaults` |
+| `metadata.ts` | stores rules through `context.metadata` / `Symbol.metadata` |
+| `types/ValidatorOptions.ts` | all decorator options |
+| `types/ValidationCode.ts` | error codes |
+| `test/validation.test.ts` | module tests |
+
+## A note on `design:type`
+
+`Reflect.getMetadata("design:type")` is deliberately not used: it requires
+`emitDecoratorMetadata` and the external `reflect-metadata` package, which breaks
+the "no dependencies, no reflection" principles. Instead the expected type is
+inferred from the rules themselves (`minLength` ⇒ string, `min` ⇒ number,
+`mustBeTrue` ⇒ boolean) or set with an explicit `type` hint.