@woltz/rich-domain 1.9.0 → 1.9.2

package/src/types/criteria.ts

@@ -0,0 +1,197 @@
+import { Primitive } from "./utils.js";
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const FILTER_OPERATORS = [
+  "equals",
+  "notEquals",
+  "greaterThan",
+  "greaterThanOrEqual",
+  "lessThan",
+  "lessThanOrEqual",
+  "contains",
+  "startsWith",
+  "endsWith",
+  "in",
+  "notIn",
+  "between",
+  "isNull",
+  "isNotNull",
+] as const;
+
+export type FilterOperator = (typeof FILTER_OPERATORS)[number];
+
+export type StringOperators =
+  | "equals"
+  | "notEquals"
+  | "contains"
+  | "startsWith"
+  | "endsWith"
+  | "in"
+  | "notIn"
+  | "isNull"
+  | "isNotNull";
+
+export type NumberOperators =
+  | "equals"
+  | "notEquals"
+  | "greaterThan"
+  | "greaterThanOrEqual"
+  | "lessThan"
+  | "lessThanOrEqual"
+  | "in"
+  | "notIn"
+  | "between"
+  | "isNull"
+  | "isNotNull";
+
+export type DateOperators =
+  | "equals"
+  | "notEquals"
+  | "greaterThan"
+  | "greaterThanOrEqual"
+  | "lessThan"
+  | "lessThanOrEqual"
+  | "in"
+  | "notIn"
+  | "between"
+  | "isNull"
+  | "isNotNull";
+
+export type BooleanOperators = "equals" | "notEquals" | "isNull" | "isNotNull";
+
+export type ArrayOperators = "in" | "notIn" | "isNull" | "isNotNull";
+
+export type OperatorsForType<T> = T extends string
+  ? StringOperators
+  : T extends number
+    ? NumberOperators
+    : T extends Date
+      ? DateOperators
+      : T extends boolean
+        ? BooleanOperators
+        : T extends Array<any>
+          ? ArrayOperators
+          : FilterOperator;
+
+export type FilterValueFor<T> =
+  | T
+  | (T extends number | Date ? [T, T] : never)
+  | T[]
+  | null;
+
+/**
+ * Resolve individual entity prop types for criteria:
+ * - Date → Date (preserved, so DateOperators are used)
+ * - Array<U> → recurse into elements
+ * - Id / ValueObject (value + equals) → unwrap to primitive value
+ * - Everything else → keep as-is
+ */
+type ResolveEntityProp<T> = T extends Date
+  ? Date
+  : T extends Array<infer U>
+    ? ResolveEntityProp<U>[]
+    : T extends { value: infer V; equals(...args: any[]): any }
+      ? V
+      : T;
+
+/**
+ * Extract the plain object type from an entity for criteria field resolution.
+ * - For entities (with `props`), resolves from raw props preserving Date types.
+ * - For objects with toJSON(), uses the return type of toJSON().
+ * - Otherwise, uses the type as is.
+ */
+type ExtractPlainType<T> = T extends { props: infer P }
+  ? { [K in keyof P]: ResolveEntityProp<P[K]> }
+  : T extends { toJSON(): infer R }
+    ? R
+    : T;
+
+export type PathValue<
+  T,
+  P extends string,
+> = P extends `${infer K}.${infer Rest}`
+  ? K extends keyof ExtractPlainType<T>
+    ? ExtractPlainType<T>[K] extends Array<infer U>
+      ? PathValue<U, Rest>
+      : PathValue<ExtractPlainType<T>[K], Rest>
+    : never
+  : P extends keyof ExtractPlainType<T>
+    ? ExtractPlainType<T>[P]
+    : never;
+
+export interface Filter<TField = string, TValue = unknown> {
+  field: TField;
+  operator: unknown extends TValue ? FilterOperator : OperatorsForType<TValue>;
+  value: TValue;
+  options?: CriteriaOptions;
+}
+
+export type TypedFilter<T> = {
+  [K in FieldPath<T>]: {
+    field: K;
+    operator: OperatorsForType<NonNullable<PathValue<T, K>>>;
+    value: FilterValueFor<NonNullable<PathValue<T, K>>>;
+    options?: CriteriaOptions;
+  };
+}[FieldPath<T>];
+
+export type CriteriaAdapter<Input, Output> = {
+  [K in FieldPath<Input>]?: FieldPath<Output>;
+};
+
+export type OrderDirection = "asc" | "desc";
+
+export interface Order {
+  field: string;
+  direction: OrderDirection;
+}
+
+export type TypedOrder<T> = {
+  field: FieldPath<T>;
+  direction: OrderDirection;
+};
+
+export interface Pagination {
+  page: number;
+  limit: number;
+  offset: number;
+}
+
+export type Search = string;
+
+export type QueryParamsObject = {
+  filters?: Record<string, unknown>;
+  pagination?: Omit<Pagination, "offset">;
+  orderBy?: string[];
+  search?: string;
+};
+
+export interface PaginationMeta {
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+  hasNext: boolean;
+  hasPrevious: boolean;
+}
+
+export interface CriteriaOptions {
+  quantifier?: "some" | "every" | "none";
+}
+
+type ExcludeBuiltInKeys<T> = Exclude<keyof T, keyof any[] | number | symbol>;
+
+export type FieldPath<T> =
+  ExtractPlainType<T> extends Primitive
+    ? never
+    : {
+        [K in ExcludeBuiltInKeys<ExtractPlainType<T>> & string]: NonNullable<
+          ExtractPlainType<T>[K]
+        > extends Primitive
+          ? K
+          : NonNullable<ExtractPlainType<T>[K]> extends Array<infer U>
+            ? U extends Primitive
+              ? K
+              : K | `${K}.${FieldPath<U>}`
+            : `${K}.${FieldPath<NonNullable<ExtractPlainType<T>[K]>>}`;
+      }[ExcludeBuiltInKeys<ExtractPlainType<T>> & string];

package/src/types/domain-event.ts

@@ -0,0 +1,29 @@
+/**
+ * Interface for all domain events
+ */
+export interface IDomainEvent<P = unknown> {
+  /**
+   * Unique identifier for this event occurrence
+   */
+  readonly eventId: string;
+
+  /**
+   * When the event occurred
+   */
+  readonly occurredOn: Date;
+
+  /**
+   * Name/type of the event (e.g., "UserCreated", "OrderPlaced")
+   */
+  readonly eventName: string;
+
+  /**
+   * Queue name for the event (optional)
+   */
+  readonly queueName?: string;
+
+  /**
+   * Payload of the event
+   */
+  readonly payload: P;
+}

package/src/types/domain.ts

@@ -0,0 +1,41 @@
+import { Id } from "../core/index";
+import { StandardSchema } from "./standard-schema.js";
+
+export interface BaseProps {
+  id: Id;
+}
+
+interface DomainValidation<T> {
+  schema: StandardSchema<T>;
+  config?: ValidationConfig;
+}
+
+export type EntityValidation<T> = DomainValidation<T>;
+export type VOValidation<T> = DomainValidation<T>;
+
+export interface VOHooks<V, VO> {
+  onBeforeCreate?: (value: V) => void;
+  rules?: (valueObject: VO) => void;
+}
+
+export interface EntityHooks<T extends BaseProps, E> {
+  onBeforeCreate?: (props: T) => void;
+  onBeforeUpdate?: (entity: E, snapshot: T) => boolean;
+  onCreate?: (entity: E) => void;
+  rules?: (entity: E) => void;
+}
+
+export interface ValidationConfig {
+  /** When true, validates the entity on creation. Default: true */
+  onCreate?: boolean;
+  /** When true, validates the entity on update. Default: true */
+  onUpdate?: boolean;
+  /** When true, throws a ValidationError when validation fails. Default: true */
+  throwOnError?: boolean;
+  /**
+   * When `throwOnError` is `false`, controls whether invalid updates are kept on the entity.
+   * - `true` (default): apply mutations and refresh `validationErrors` (dirty / form mode).
+   * - `false`: block mutations when errors already exist, and revert updates that fail validation.
+   */
+  persistInvalidMutations?: boolean;
+}

package/src/types/event-bus.ts

@@ -0,0 +1,17 @@
+import { IDomainEvent } from "./domain-event";
+
+export interface IDomainEventBus {
+  /**
+   * Publish a single domain event.
+   *
+   * @param event - The domain event to publish
+   */
+  publish(event: IDomainEvent): Promise<void>;
+
+  /**
+   * Publish multiple domain events.
+   *
+   * @param events - Array of domain events to publish
+   */
+  publishAll(events: IDomainEvent[]): Promise<void>;
+}

package/src/types/index.ts

@@ -0,0 +1,9 @@
+export * from "./criteria.js";
+export * from "./domain.js";
+export * from "./standard-schema.js";
+export * from "./utils.js";
+export * from "./unit-of-work.js";
+export * from "./domain-event.js";
+export * from "./change-tracker.js";
+export * from "./event-bus.js";
+export * from "./outbox-store.js";

package/src/types/outbox-store.ts

@@ -0,0 +1,97 @@
+import { IDomainEvent } from "./domain-event.js";
+
+/**
+ * Possible statuses for an outbox entry.
+ *
+ * - `pending`: The event has been persisted but not yet published.
+ * - `published`: The event has been successfully published to the message broker.
+ * - `failed`: The event failed to publish after the maximum number of retries.
+ */
+export type OutboxStatus = "pending" | "published" | "failed";
+
+/**
+ * The data shape of a single outbox entry returned by {@link IOutboxStore.fetchPending}.
+ * This is the flat wire format — no class logic, just data.
+ */
+export interface OutboxEntryData {
+  /** The event's own `eventId`, used as the primary key of the outbox table. */
+  id: string;
+  /** The event class name (e.g. `"OrderPlaced"`). */
+  eventName: string;
+  /** The event payload (the `P` generic from `DomainEvent<P>`). */
+  payload: unknown;
+  /** When the domain event was originally created. */
+  occurredOn: Date;
+  /** Current publish status. */
+  status: OutboxStatus;
+  /** Number of publish attempts so far. */
+  retries: number;
+  /** Error message from the most recent failed publish attempt, if any. */
+  lastError: string | null;
+  /** When this outbox row was inserted. */
+  createdAt: Date;
+}
+
+/**
+ * Result returned by {@link IOutboxStore.fetchPending}.
+ */
+export interface OutboxFetchResult {
+  entries: OutboxEntryData[];
+}
+
+/**
+ * Minimal, framework-agnostic contract for an outbox persistence store.
+ *
+ * Implementations exist for Prisma, Drizzle, TypeORM, and raw SQL.
+ * The interface lives in `@woltz/rich-domain` (core) so that the
+ * `@woltz/rich-domain-outbox` package can depend on it without
+ * coupling to any specific ORM or database.
+ */
+export interface IOutboxStore {
+  /**
+   * Persist one or more domain events to the outbox table.
+   *
+   * MUST be called within the same database transaction as the aggregate write
+   * so that both succeed or both roll back together.
+   *
+   * Each event's `eventId` becomes the primary key (`id`) of the outbox row.
+   * The `status` column is always set to `"pending"` initially.
+   *
+   * @param events  - The domain events to persist.
+   * @param tx      - Optional ORM-specific transaction context (e.g. a Prisma interactive tx client, a Drizzle tx, or a TypeORM EntityManager).
+   */
+  save(events: IDomainEvent[], tx?: unknown): Promise<void>;
+
+  /**
+   * Fetch a batch of events whose status is still `"pending"`.
+   * Entries are returned in insertion order (oldest first) so that
+   * earlier events are retried before later ones.
+   *
+   * The publisher calls this periodically and attempts to publish each entry.
+   * On success it calls {@link markPublished}; on failure it calls {@link markFailed}.
+   *
+   * @param batchSize - Maximum number of entries to return. Default 50.
+   * @returns A result object containing the matching entries.
+   */
+  fetchPending(batchSize?: number): Promise<OutboxFetchResult>;
+
+  /**
+   * Mark an outbox entry as successfully published.
+   *
+   * Mapping: `UPDATE outbox SET status = 'published' WHERE id = :eventId`
+   *
+   * @param id - The event's `eventId` (same value used as the outbox primary key).
+   */
+  markPublished(id: string): Promise<void>;
+
+  /**
+   * Mark an outbox entry as failed, incrementing its retry counter
+   * and recording the error that caused the failure.
+   *
+   * Mapping: `UPDATE outbox SET status = 'failed', retries = retries + 1, lastError = :error WHERE id = :eventId`
+   *
+   * @param id    - The event's `eventId`.
+   * @param error - The error message.
+   */
+  markFailed(id: string, error: string): Promise<void>;
+}

package/src/types/standard-schema.ts

@@ -0,0 +1,19 @@
+export interface StandardSchemaIssue {
+  message: string;
+  path?: ReadonlyArray<unknown>;
+}
+
+export interface StandardSchemaResult<T> {
+  value?: T;
+  issues?: ReadonlyArray<StandardSchemaIssue>;
+}
+
+export interface StandardSchemaProps<T> {
+  validate: (
+    value: unknown
+  ) => StandardSchemaResult<T> | Promise<StandardSchemaResult<T>>;
+}
+
+export interface StandardSchema<T = unknown> {
+  "~standard": StandardSchemaProps<T>;
+}

package/src/types/unit-of-work.ts

@@ -0,0 +1,46 @@
+import { Aggregate } from "../core/index";
+import { Repository } from "../repository/base-repository.js";
+
+/**
+ * Transaction context for Unit of Work
+ */
+export interface TransactionContext {
+  /**
+   * Commit all changes
+   */
+  commit(): Promise<void>;
+
+  /**
+   * Rollback all changes
+   */
+  rollback(): Promise<void>;
+
+  /**
+   * Check if transaction is active
+   */
+  isActive(): boolean;
+}
+
+/**
+ * Unit of Work interface
+ * Manages transactions across multiple repositories
+ */
+export interface IUnitOfWork {
+  /**
+   * Start a new transaction
+   */
+  begin(): Promise<TransactionContext>;
+
+  /**
+   * Execute work within a transaction
+   * Auto-commits on success, rolls back on error
+   */
+  transaction<T>(work: (ctx: TransactionContext) => Promise<T>): Promise<T>;
+
+  /**
+   * Get repository within transaction context
+   */
+  getRepository<TDomain extends Aggregate<any>>(
+    repository: new (...args: any[]) => Repository<TDomain>
+  ): Repository<TDomain>;
+}

package/src/types/utils.ts

@@ -0,0 +1,24 @@
+import { Id, ValueObject } from "../core/index";
+
+type JsonPrimitive = string | number | boolean | null;
+
+export type DeepJsonResult<T> = T extends Id
+  ? string
+  : T extends ValueObject<infer U>
+    ? U
+    : T extends Date
+      ? string
+      : T extends Array<infer U>
+        ? DeepJsonResult<U>[]
+        : T extends { toJSON(): infer R }
+          ? DeepJsonResult<R>
+          : T extends object
+            ? { [K in keyof T]: DeepJsonResult<T[K]> }
+            : T extends JsonPrimitive
+              ? T
+              : never;
+
+export type Primitive = string | number | boolean | Date | null | undefined;
+export type UnwrapArray<T> = T extends Array<infer U> ? U : never;
+export type IsArray<T> = T extends Array<any> ? true : false;
+export type NonUndefined<T> = T extends undefined ? never : T;

package/src/utils/criteria-operator-validation.ts

@@ -0,0 +1,209 @@
+import { FILTER_OPERATORS } from "../index.js";
+import {
+  ArrayOperators,
+  BooleanOperators,
+  DateOperators,
+  FilterOperator,
+  NumberOperators,
+  StringOperators,
+} from "../types/index.js";
+
+const FORCE_STRING_OPERATORS = new Set(["contains", "startsWith", "endsWith"]);
+
+export function sanitizeFieldValue(
+  value: unknown,
+  operator: FilterOperator
+): unknown {
+  if (value === null || value === undefined) {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeFieldValue(item, operator));
+  }
+
+  if (value instanceof Date) {
+    return value;
+  }
+
+  const stringValue = String(value).trim();
+
+  if (stringValue === "") {
+    return "";
+  }
+
+  if (operator && FORCE_STRING_OPERATORS.has(operator)) {
+    return stringValue;
+  }
+
+  if (stringValue === "true" || stringValue === "false") {
+    return stringValue === "true";
+  }
+
+  const numberValue = Number(stringValue);
+  if (!Number.isNaN(numberValue)) {
+    return numberValue;
+  }
+
+  const dateObj = new Date(stringValue);
+  if (!Number.isNaN(dateObj.getTime())) {
+    return dateObj;
+  }
+
+  return stringValue;
+}
+
+export function isValidOperatorForType(
+  value: unknown,
+  operator: FilterOperator
+): boolean {
+  const sanitizedValue = sanitizeFieldValue(value, operator);
+
+  if (
+    operator === "between" &&
+    Array.isArray(sanitizedValue) &&
+    sanitizedValue.length === 2
+  ) {
+    const elementType = typeof sanitizedValue[0];
+    if (elementType === "number" || sanitizedValue[0] instanceof Date) {
+      return true;
+    }
+    return false;
+  }
+
+  const valueType = typeof sanitizedValue;
+
+  if (valueType === "string") {
+    const validOps: StringOperators[] = [
+      "equals",
+      "notEquals",
+      "contains",
+      "startsWith",
+      "endsWith",
+      "in",
+      "notIn",
+      "isNull",
+      "isNotNull",
+    ];
+    return validOps.includes(operator as StringOperators);
+  }
+
+  if (valueType === "number") {
+    const validOps: NumberOperators[] = [
+      "equals",
+      "notEquals",
+      "greaterThan",
+      "greaterThanOrEqual",
+      "lessThan",
+      "lessThanOrEqual",
+      "in",
+      "notIn",
+      "between",
+      "isNull",
+      "isNotNull",
+    ];
+    return validOps.includes(operator as NumberOperators);
+  }
+
+  if (valueType === "boolean") {
+    const validOps: BooleanOperators[] = [
+      "equals",
+      "notEquals",
+      "isNull",
+      "isNotNull",
+    ];
+    return validOps.includes(operator as BooleanOperators);
+  }
+
+  if (sanitizedValue instanceof Date) {
+    const validOps: DateOperators[] = [
+      "equals",
+      "notEquals",
+      "greaterThan",
+      "greaterThanOrEqual",
+      "lessThan",
+      "lessThanOrEqual",
+      "in",
+      "notIn",
+      "between",
+      "isNull",
+      "isNotNull",
+    ];
+    return validOps.includes(operator as DateOperators);
+  }
+
+  if (Array.isArray(sanitizedValue)) {
+    const validOps: ArrayOperators[] = ["in", "notIn", "isNull", "isNotNull"];
+    return validOps.includes(operator as ArrayOperators);
+  }
+
+  return true;
+}
+
+export function getValidOperatorsForType(value: unknown): FilterOperator[] {
+  if (value === null || value === undefined) {
+    return ["isNull", "isNotNull", "equals", "notEquals"];
+  }
+
+  const valueType = typeof value;
+
+  if (valueType === "string" && Number.isNaN(Number(value))) {
+    return [
+      "equals",
+      "notEquals",
+      "contains",
+      "startsWith",
+      "endsWith",
+      "in",
+      "notIn",
+      "isNull",
+      "isNotNull",
+    ];
+  }
+
+  if (valueType === "number") {
+    return [
+      "equals",
+      "notEquals",
+      "greaterThan",
+      "greaterThanOrEqual",
+      "lessThan",
+      "lessThanOrEqual",
+      "in",
+      "notIn",
+      "between",
+      "isNull",
+      "isNotNull",
+    ];
+  }
+
+  if (valueType === "boolean") {
+    return ["equals", "notEquals", "isNull", "isNotNull"];
+  }
+
+  if (value instanceof Date) {
+    return [
+      "equals",
+      "notEquals",
+      "greaterThan",
+      "greaterThanOrEqual",
+      "lessThan",
+      "lessThanOrEqual",
+      "in",
+      "notIn",
+      "between",
+      "isNull",
+      "isNotNull",
+    ];
+  }
+
+  if (Array.isArray(value)) {
+    return ["in", "notIn", "isNull", "isNotNull"];
+  }
+
+  return [...FILTER_OPERATORS];
+}
+
+export function isOperator(value: string): value is FilterOperator {
+  return FILTER_OPERATORS.includes(value as FilterOperator);
+}