drimion 0.1.12 → 0.2.0

package/README.md

@@ -28,6 +28,7 @@ A developer-first CLI tool for bringing Domain-Driven Design (DDD) primitives in
   - [Entity](#entity)
   - [Aggregate](#aggregate)
   - [Repository](#repository)
+  - [Specification](#specification)
   - [Use Cases](#use-cases)
 - [API Reference](#api-reference)
   - [Core API](#core-api)
@@ -83,7 +84,7 @@ Instead, it:
 Domain-Driven Design organizes code into layers of responsibility. This library provides the building blocks for the **Domain Layer** and defines the contracts for the **Application** and **Infrastructure** layers.
 
 ```
-┌─────────────────────────────────────────────────┐
+┌──────────────────────────────────────────────────┐
 │                  Application Layer               │
 │  Use Cases · Commands · Queries · Event Handlers │
 ├──────────────────────────────────────────────────┤
@@ -111,7 +112,6 @@ Key DDD principles this library embraces:
 | `ValueObject` | ❌ By value | ❌ Immutable | ❌           | Domain concept defined entirely by its properties      |
 | `Entity`      | ✅ By `id`  | ✅           | ❌           | Domain object with stable identity and lifecycle       |
 | `Aggregate`   | ✅ By `id`  | ✅           | ✅           | Consistency boundary; single entry point for mutations |
-| `ID`          | —           | —            | —            | Typed unique identifier (UUID or custom)               |
 
 ---
 
@@ -132,7 +132,7 @@ yarn dlx drimion init
 pnpm dlx drimion init
 
 # bun
-bunx --bun drimion init
+bun x drimion init
 ```
 
 Running `init -y` will skip interactive prompts and install defaults and:
@@ -336,14 +336,53 @@ await bus.publishAll(order.pullEvents()); // then publish
 A **Repository** is the persistence contract for an aggregate. The interface is defined in the **domain layer** and implemented in the **infrastructure layer** — keeping your domain code free of storage concerns.
 
 ```typescript
-class UserRepository extends BaseRepository<User> {
-  async findById(id: string): Promise<IResult<User, string>> {
+// defined within the domain layer as port
+interface IUserRepository extends BaseRepository<User> {
+  findById(id: UID): Promise<User | null>
+  save(user: User): Promise<void>
+  delete(id: UID): Promise<void>
+  exists(id: UID): Promise<boolean>
+}
+
+// defined within the infra layer as adapter
+class UserRepository extends IUserRepository {
+  async findById(id: string): Promise<User> {
+    /* ... */
+  }
+  async save(user: User): Promise<void> {
+    /* ... */
+  }
+  async delete(id: string): Promise<void> {
+    /* ... */
+  }
+  async exists(id: string): Promise<boolean> {
+    /* ... */
+  }
+}
+
+class DrizzleORMUserRepository extends IUserRepository {
+  async findById(id: string): Promise<User> {
+    /* ... */
+  }
+  async save(user: User): Promise<void> {
+    /* ... */
+  }
+  async delete(id: string): Promise<void> {
     /* ... */
   }
-  async save(user: User): Promise<IResult<void, string>> {
+  async exists(id: string): Promise<boolean> {
+    /* ... */
+  }
+}
+
+class PrismaORMUserRepository extends IUserRepository {
+  async findById(id: string): Promise<User> {
     /* ... */
   }
-  async delete(id: string): Promise<IResult<void, string>> {
+  async save(user: User): Promise<void> {
+    /* ... */
+  }
+  async delete(id: string): Promise<void> {
     /* ... */
   }
   async exists(id: string): Promise<boolean> {
@@ -352,6 +391,59 @@ class UserRepository extends BaseRepository<User> {
 }
 ```
 
+### Specification
+
+A **Specification** encapsulates a single, named business rule as a pure predicate. Instead of scattering `if` conditions across use cases and domain methods, you give each rule a name that lives in your ubiquitous language — and compose rules together without subclassing.
+
+Three scenarios where specifications belong:
+
+1. **Validation** — guard Aggregate domain methods against invalid state transitions.
+2. **In-memory selection** — filter already-loaded collections by business criteria.
+3. **Construction criteria** — express what a valid candidate must look like before building something.
+
+> ⚠️ Specifications are **not** intended to drive persistence queries. Repository methods should accept explicit parameters and delegate to the ORM/query builder directly — translating a spec into SQL couples domain rules to infrastructure.
+
+```typescript
+// Define — implement `satisfiedBy`, not `isSatisfiedBy`
+class MinimumOrderAmountSpec extends BaseSpecification<Order> {
+  constructor(private readonly minimum: number) { super(); }
+
+  protected satisfiedBy(order: Order): boolean {
+    return order.get('total') >= this.minimum;
+  }
+}
+
+class IsPaidSpec extends BaseSpecification<Order> {
+  protected satisfiedBy(order: Order): boolean {
+    return order.get('isPaid') === true;
+  }
+}
+
+class IsFraudSpec extends BaseSpecification<Order> {
+  protected satisfiedBy(order: Order): boolean {
+    return order.get('isFraud') === true;
+  }
+}
+
+// Compose — .and() / .or() / .not()
+const eligibleForShipping = new MinimumOrderAmountSpec(100)
+  .and(new IsPaidSpec())
+  .and(new IsFraudSpec().not());
+
+// Guard inside an Aggregate domain method
+ship(): void {
+  const spec = new MinimumOrderAmountSpec(100).and(new IsPaidSpec());
+  if (!spec.isSatisfiedBy(this)) {
+    throw new DomainError('Order is not eligible for shipping', { context: 'Order' });
+  }
+  this.change('status', 'shipped');
+  this.emit({ type: 'order:shipped' });
+}
+
+// In-memory selection
+const eligible = orders.filter(o => eligibleForShipping.isSatisfiedBy(o));
+```
+
 ### Use Cases
 
 Use cases are the entry points to your application logic. This library provides two interfaces to model them: `ICommand` for operations that mutate state, and `IQuery` for read-only operations.
@@ -498,6 +590,26 @@ abstract class BaseRepository<T extends Entity, ID = UID> {
 }
 ```
 
+#### Specification
+
+```typescript
+// Extend BaseSpecification<T> and implement satisfiedBy()
+class MySpec extends BaseSpecification<MyType> {
+  protected satisfiedBy(candidate: MyType): boolean { /* rule */ }
+}
+
+// Evaluate
+spec.isSatisfiedBy(candidate)  // → boolean
+
+// Compose — each returns a new ISpecification<T>
+spec.and(other)  // both must be satisfied
+spec.or(other)   // either must be satisfied
+spec.not()       // negates this spec
+
+// Chain freely
+new ASpec().and(new BSpec()).or(new CSpec().not()).and(new DSpec())
+```
+
 #### Adapters
 
 ```typescript
@@ -592,44 +704,12 @@ Thrown automatically by:
 - `init()` — `isValidProps()` returns `false`
 - Event managers — event name missing `context:EventName` format
 
-#### Iterator
-
-Bi-directional sequential traversal over a collection.
-
-```typescript
-// Create
-Iterator.create({ initialData, restartOnFinish?, returnCurrentOnReversion? })
-
-// Navigate
-iter.next()     // move forward, return item
-iter.prev()     // move backward, return item
-iter.hasNext()  // boolean
-iter.hasPrev()  // boolean
-iter.first()    // peek first item (no cursor move)
-iter.last()     // peek last item (no cursor move)
-iter.toFirst()  // reset cursor to before first item
-iter.toLast()   // reset cursor to after last item
-
-// Mutate
-iter.add(item)          // alias for addToEnd
-iter.addToEnd(item)
-iter.addToStart(item)   // resets cursor
-iter.removeFirst()
-iter.removeLast()
-iter.removeItem(item)   // by JSON equality, adjusts cursor
-iter.clear()
-
-// Export
-iter.toArray()   // copy as plain array
-iter.clone()     // new Iterator with same items and config
-iter.total()     // item count
-iter.isEmpty()   // boolean
-```
-
 #### Validators & Utils
 
 Built-in `validator` and `util` instances inherited by all domain classes, accessible as both instance and static members.
 
+
+
 **Type guards:**
 
 ```typescript
@@ -642,6 +722,18 @@ this.validator.isID(v)         this.validator.isEntity(v)
 this.validator.isAggregate(v)  this.validator.isValueObject(v)
 ```
 
+> You can also import the instance directly from the kernel using the lowercase name exports
+
+```typescript
+// import the instance instead of using it inside class through `this` context
+import { validator, utils } from "{your-import-alias}"
+
+function myFunctionOutsideOfClass() {
+  validator.string("Some string")
+  utils.string("some string")
+}
+```
+
 **String checks:** `hasLengthBetweenOrEqual(min, max)` · `hasLengthGreaterThan(n)` · `hasLengthLessOrEqualTo(n)` · `hasLengthEqualTo(n)` · `isEmpty()` · `hasSpecialChar()` · `hasOnlyNumbers()` · `hasOnlyLetters()` · `match(regex)` · `isEqual(str)` · `includes(str)`
 
 **Number checks:** `isPositive()` · `isNegative()` · `isGreaterThan(n)` · `isGreaterOrEqualTo(n)` · `isLessThan(n)` · `isLessOrEqualTo(n)` · `isBetween(min, max)` · `isBetweenOrEqual(min, max)` · `isEqualTo(n)` · `isInteger()` · `isSafeInteger()` · `isEven()`
@@ -663,8 +755,8 @@ Aggregate (emits) ──→ pullEvents() ──→ [ Your Transport ]
                                                │
                            ┌───────────────────┼──────────────────────┐
                            ▼                   ▼                      ▼
-                        EventBus          Redis / Kafka          Custom IEventBus
-                     (in-process)       (distributed)             (anything)
+                        EventBus          Redis / Kafka        Custom IEventBus
+                      (in-process)        (distributed)           (anything)
 ```
 
 #### Domain Event
@@ -952,4 +1044,4 @@ remove it. So you can still remove the config file or library directory manually
 
 ## License
 
-Licensed under the MIT License.
+Licensed under the MIT License.

package/dist/cli/index.js

@@ -219,7 +219,7 @@ function resolvePackageManager() {
   if (true) {
     return {
       __PKG_NAME__: "drimion",
-      __PKG_VERSION__: "0.1.12",
+      __PKG_VERSION__: "0.2.0",
       __PKG_REPOSITORY__: "git+https://github.com/bramadl/drimion.git"
     };
   }

package/dist/cli/templates/repository.ts.hbs

@@ -1,4 +1,6 @@
 import type { BaseRepository } from "@pokepulse/kernel";
 // import { {{className}} } from "./path-to-your-{{lowerName}}";
 
-export interface I{{className}}Repository extends BaseRepository<{{className}}> {}
+export interface I{{className}}Repository extends BaseRepository<{{className}}> {
+  // add your custom method
+}

package/dist/cli/templates/use-case.ts.hbs

@@ -9,16 +9,9 @@ export type {{className}}Output = {
 }
 
 export type {{className}}Metadata = {
-  // define metadata - use never if no input needed or `AnyObject` for empty object
+  // define metadata - use never if no metadata needed
 }
 
-/**
- * @note
- * In order to avoid this TS error:
- * `A class can only implement an object type or intersection of object types with statically known members`.
- *
- * Decide wether you want to use `IQuery` or `ICommand` then change the `IUseCase` usage into one of them.
- */
 export class {{className}} implements IUseCase<{{className}}Input, {{className}}Output> {
   public constructor() {}
   

package/dist/kernel/core/entity.ts

@@ -2,8 +2,8 @@
 /** biome-ignore-all lint/complexity/noThisInStatic: Required for polymorphic `this` in base factory (DDD pattern). */
 
 import { AutoMapper } from "../helpers/auto-mapper";
-import { DomainError } from "../helpers/domain-error";
 import { GettersAndSetters } from "../helpers/getters-setters";
+import { DomainError } from "../libs/domain-error";
 import { Result } from "../libs/result";
 import type { Adapter, IAdapter } from "../types/adapter.types";
 import type {

package/dist/kernel/core/index.ts

@@ -1,5 +1,7 @@
 export { Aggregate } from "./aggregate";
+export { BaseDomainEvent } from "./domain-event";
 export { Entity } from "./entity";
 export { ID, Id } from "./id";
 export { BaseRepository } from "./repository";
+export { BaseSpecification } from "./specification";
 export { ValueObject } from "./value-object";

package/dist/kernel/core/specification.ts

@@ -0,0 +1,180 @@
+import type { ISpecification } from "../types/specification.types";
+
+/**
+ * @description
+ * Abstract base class for all domain specifications.
+ *
+ * A `Specification` is a pure predicate — it answers one question: does this
+ * candidate satisfy the rule? Nothing more. Error messaging and failure context
+ * are concerns of the caller (domain method, application layer) via `DomainError`.
+ *
+ * Specifications are:
+ * - **Named** — each subclass carries a meaningful ubiquitous-language name.
+ * - **Composable** — combine via `.and()`, `.or()`, `.not()` without subclassing.
+ * - **Pure** — no side effects, no I/O, no error state.
+ *
+ * **Three use cases (Evans):**
+ * 1. **Validation** — guard Aggregate domain methods against invalid state transitions.
+ * 2. **In-memory selection** — filter already-loaded collections.
+ * 3. **Construction criteria** — express what a valid object must look like.
+ *
+ * Specifications are **not** intended to drive persistence queries. Repository
+ * methods should use explicit parameters and delegate to the ORM/query builder
+ * directly — translating specs to SQL couples domain rules to infrastructure.
+ *
+ * **Implementing a specification**
+ *
+ * Extend `BaseSpecification<T>` and implement the `protected satisfiedBy()` method.
+ * Never override `isSatisfiedBy` — the base class owns that method.
+ *
+ * @template T The type of the candidate being evaluated.
+ *
+ * @example
+ * ```typescript
+ * // 1. Define
+ * class MinimumOrderAmountSpec extends BaseSpecification<Order> {
+ *     constructor(private readonly minimum: number) { super(); }
+ *
+ *     protected satisfiedBy(order: Order): boolean {
+ *         return order.get('total') >= this.minimum;
+ *     }
+ * }
+ *
+ * // 2. Compose
+ * const eligible = new MinimumOrderAmountSpec(100)
+ *     .and(new IsPaidSpec())
+ *     .and(new IsFraudSpec().not());
+ *
+ * // 3. Guard inside an Aggregate domain method
+ * ship(): void {
+ *     if (!new MinimumOrderAmountSpec(100).and(new IsPaidSpec()).isSatisfiedBy(this)) {
+ *         throw new DomainError('Order is not eligible for shipping', { context: 'Order' });
+ *     }
+ *     this.change('status', 'shipped');
+ *     this.emit({ type: 'order:shipped' });
+ * }
+ *
+ * // 4. In-memory selection
+ * const eligibleOrders = orders.filter(o => eligible.isSatisfiedBy(o));
+ * ```
+ */
+export abstract class BaseSpecification<T> implements ISpecification<T> {
+	/**
+	 * @description
+	 * Marker used by `Validator.isSpecification()` to identify this instance
+	 * without an `instanceof` check (avoids circular imports).
+	 * @internal
+	 */
+	protected readonly __kind = "Specification" as const;
+
+	/**
+	 * @description
+	 * Implement the business rule here.
+	 *
+	 * Called internally by `isSatisfiedBy`. Do **not** call this method directly.
+	 *
+	 * @param candidate The domain object to evaluate.
+	 * @returns `true` if the candidate satisfies the rule; `false` otherwise.
+	 */
+	protected abstract satisfiedBy(candidate: T): boolean;
+
+	/**
+	 * @description
+	 * Evaluates whether the candidate satisfies this specification.
+	 *
+	 * Delegates to `satisfiedBy()` — do not override this method in subclasses.
+	 *
+	 * @param candidate The domain object to evaluate.
+	 * @returns `true` if satisfied; `false` otherwise.
+	 */
+	public isSatisfiedBy(candidate: T): boolean {
+		return this.satisfiedBy(candidate);
+	}
+
+	/**
+	 * @description
+	 * Returns a new specification satisfied only when **both** this and `other`
+	 * are satisfied (logical AND).
+	 *
+	 * @example
+	 * ```typescript
+	 * const spec = new MinimumAmountSpec(100).and(new IsPaidSpec());
+	 * ```
+	 */
+	public and(other: ISpecification<T>): ISpecification<T> {
+		return new AndSpecification(this, other as BaseSpecification<T>);
+	}
+
+	/**
+	 * @description
+	 * Returns a new specification satisfied when **either** this or `other`
+	 * is satisfied (logical OR).
+	 *
+	 * @example
+	 * ```typescript
+	 * const spec = new IsVipSpec().or(new HasCouponSpec());
+	 * ```
+	 */
+	public or(other: ISpecification<T>): ISpecification<T> {
+		return new OrSpecification(this, other as BaseSpecification<T>);
+	}
+
+	/**
+	 * @description
+	 * Returns a new specification satisfied when this specification is **not**
+	 * satisfied (logical NOT).
+	 *
+	 * @example
+	 * ```typescript
+	 * const spec = new IsFraudSpec().not();
+	 * ```
+	 */
+	public not(): ISpecification<T> {
+		return new NotSpecification(this);
+	}
+}
+
+// ─── Composite Implementations ───────────────────────────────────────────────
+
+/** @internal */
+class AndSpecification<T> extends BaseSpecification<T> {
+	constructor(
+		private readonly left: BaseSpecification<T>,
+		private readonly right: BaseSpecification<T>,
+	) {
+		super();
+	}
+
+	protected satisfiedBy(candidate: T): boolean {
+		return (
+			this.left.isSatisfiedBy(candidate) && this.right.isSatisfiedBy(candidate)
+		);
+	}
+}
+
+/** @internal */
+class OrSpecification<T> extends BaseSpecification<T> {
+	constructor(
+		private readonly left: BaseSpecification<T>,
+		private readonly right: BaseSpecification<T>,
+	) {
+		super();
+	}
+
+	protected satisfiedBy(candidate: T): boolean {
+		return (
+			this.left.isSatisfiedBy(candidate) || this.right.isSatisfiedBy(candidate)
+		);
+	}
+}
+
+/** @internal */
+class NotSpecification<T> extends BaseSpecification<T> {
+	constructor(private readonly wrapped: BaseSpecification<T>) {
+		super();
+	}
+
+	protected satisfiedBy(candidate: T): boolean {
+		return !this.wrapped.isSatisfiedBy(candidate);
+	}
+}

package/dist/kernel/core/value-object.ts

@@ -2,8 +2,8 @@
 /** biome-ignore-all lint/complexity/noThisInStatic: Required for polymorphic `this` in base factory (DDD pattern). */
 
 import { AutoMapper } from "../helpers/auto-mapper";
-import { DomainError } from "../helpers/domain-error";
 import { GettersAndSetters } from "../helpers/getters-setters";
+import { DomainError } from "../libs/domain-error";
 import { Result } from "../libs/result";
 import type { Adapter, IAdapter } from "../types/adapter.types";
 import type { IResult } from "../types/result.types";

package/dist/kernel/events/event-utils.ts

@@ -1,4 +1,4 @@
-import { DomainError } from "../helpers";
+import { DomainError } from "../libs";
 
 /**
  * @description

package/dist/kernel/events/index.ts

@@ -1,7 +1,5 @@
-export { BrowserEventManager, type WindowLike } from "./browser-event-manager";
-export { BaseDomainEvent } from "./domain-event";
+export { BrowserEventManager } from "./browser-event-manager";
 export { EventBus } from "./event-bus";
 export { EventContext } from "./event-context";
 export { BaseEventManager } from "./event-manager";
-export { ValidateEventName } from "./event-utils";
 export { ServerEventManager } from "./server-event-manager";

package/dist/kernel/events/server-event-manager.ts

@@ -1,4 +1,5 @@
 import { EventEmitter } from "node:events";
+
 import type { DomainEventPayload, EventEntry } from "../types/event.types";
 import { BaseEventManager } from "./event-manager";
 import { ValidateEventName } from "./event-utils";

package/dist/kernel/helpers/auto-mapper.ts

@@ -5,7 +5,7 @@ import type { AnyObject } from "../types/utils.types";
  * @description
  * Defines the shape of data used for mapping an entity's properties.
  */
-export interface EntityAutoMapperPayload {
+interface EntityAutoMapperPayload {
 	id: string;
 	createdAt: Date;
 	updatedAt: Date;

package/dist/kernel/helpers/getters-setters.ts

@@ -1,16 +1,16 @@
 import { ID } from "../core/id";
+import { DomainError } from "../libs/domain-error";
 import utils, { type Utils } from "../libs/utils";
 import validator, { type Validator } from "../libs/validator";
 import type { UID } from "../types/uid.types";
 import type { AnyObject } from "../types/utils.types";
-import { DomainError } from "./domain-error";
 
 /**
  * @description
  * Discriminator indicating which domain primitive this instance belongs to.
  * Used internally to apply different mutation behaviors for `ValueObject` vs `Entity`.
  */
-export type ParentKind = "ValueObject" | "Entity";
+type ParentKind = "ValueObject" | "Entity";
 
 /**
  * @description
@@ -20,7 +20,7 @@ export type ParentKind = "ValueObject" | "Entity";
  * Disabling getters or setters can be useful when enforcing strict encapsulation
  * or building read-only / write-only domain primitives.
  */
-export interface GettersSettersConfig {
+interface GettersSettersConfig {
 	/**
 	 * @description
 	 * When `true`, calling `get()` on this instance will throw a `DomainError`.
@@ -245,10 +245,10 @@ export abstract class GettersAndSetters<Props> {
 	 * const raw = stringVo.get('value'); // 'hello'
 	 * ```
 	 */
-	public get<Key extends keyof Props>(key: Key): Readonly<Props[Key]>;
+	public get<Key extends keyof Props>(key: Key): Props[Key];
 	public get(
 		key: "value",
-	): Readonly<"value" extends keyof Props ? Props["value"] : Props>;
+	): "value" extends keyof Props ? Props["value"] : Props;
 	/** biome-ignore lint/suspicious/noExplicitAny: TS cannot correlate overload branches with runtime narrowing. */
 	public get(key: any): any {
 		if (this.config.disableGetters) {

package/dist/kernel/helpers/index.ts

@@ -1,7 +1 @@
-export type { EntityAutoMapperPayload } from "./auto-mapper";
-export { AutoMapper } from "./auto-mapper";
-export type { CreateManyResult } from "./domain-classes";
-export { DomainClasses } from "./domain-classes";
-export { DomainError } from "./domain-error";
-export type { GettersSettersConfig, ParentKind } from "./getters-setters";
-export { GettersAndSetters } from "./getters-setters";
+export { Iterator } from "./iterator";

package/dist/kernel/index.ts

@@ -1,77 +1,79 @@
 // ── Core domain primitives ─────────────────────────────────────────────────
-export { Aggregate } from "./core/aggregate";
-export { Entity } from "./core/entity";
-export { ID, Id } from "./core/id";
-export { BaseRepository } from "./core/repository";
-export { ValueObject } from "./core/value-object";
+export {
+	Aggregate,
+	BaseDomainEvent,
+	BaseRepository,
+	BaseSpecification,
+	Entity,
+	ID,
+	Id,
+	ValueObject,
+} from "./core";
+
 // ── Event system ───────────────────────────────────────────────────────────
-export type { WindowLike } from "./events/browser-event-manager";
-export { BrowserEventManager } from "./events/browser-event-manager";
-export { BaseDomainEvent } from "./events/domain-event";
-export { EventBus } from "./events/event-bus";
-export { EventContext } from "./events/event-context";
-export { BaseEventManager } from "./events/event-manager";
-export { ValidateEventName } from "./events/event-utils";
-export { ServerEventManager } from "./events/server-event-manager";
+export {
+	BaseEventManager,
+	BrowserEventManager,
+	EventBus,
+	EventContext,
+	ServerEventManager,
+} from "./events";
+
 // ── Helpers ────────────────────────────────────────────────────────────────
-export type { EntityAutoMapperPayload } from "./helpers/auto-mapper";
-export { AutoMapper } from "./helpers/auto-mapper";
-export type { CreateManyResult } from "./helpers/domain-classes";
-export { DomainClasses } from "./helpers/domain-classes";
-export { DomainError } from "./helpers/domain-error";
-export type {
-	GettersSettersConfig,
-	ParentKind,
-} from "./helpers/getters-setters";
-export { GettersAndSetters } from "./helpers/getters-setters";
+export { Iterator } from "./helpers";
 
 // ── Libs ───────────────────────────────────────────────────────────────────
-export { Iterator } from "./libs/iterator";
-export { Result } from "./libs/result";
-export { Utils } from "./libs/utils";
-export { Validator } from "./libs/validator";
+export {
+	DomainClasses,
+	DomainError,
+	Result,
+	Utils,
+	UUID,
+	utils,
+	Validator,
+	validator,
+} from "./libs";
 
 // ── Types ──────────────────────────────────────────────────────────────────
-export type { Adapter, IAdapter } from "./types/adapter.types";
-export type { ICommand, IQuery, IUseCase } from "./types/command.types";
-export type {
-	AggregateConstructor,
-	EntityConstructor,
-	EntityProps,
-	IEntityProps,
-	IEntitySettings,
-} from "./types/entity.types";
 export type {
+	Adapter,
+	AnyObject,
 	DomainEvent,
-	DomainEventPayload,
-	EventEntry,
+	EventSubscriber,
+	IAdapter,
+	ICommand,
 	IEventBus,
-} from "./types/event.types";
-export type { IIterator, IIteratorConfig } from "./types/iterator.types";
-export type {
-	IResult,
-	IResultExecuteFn,
-	IResultHook,
-	IResultObject,
-	IResultOption,
-} from "./types/result.types";
-export type { UID } from "./types/uid.types";
-export type {
-	AnyObject,
-	BuiltIns,
-	CalcOpt,
-	Primitive,
+	IQuery,
+	ISpecification,
+	IUseCase,
 	ReadonlyDeep,
-} from "./types/utils.types";
-export type {
-	IValueObjectSettings,
-	ValueObjectConstructor,
-} from "./types/value-object.types";
+	UID,
+} from "./types";
 
 // ── Utils ──────────────────────────────────────────────────────────────────
-export { DeepFreeze, StableStringify } from "./utils/object.utils";
-export { InvalidPropsType } from "./utils/type.utils";
-
-import validator from "./libs/validator";
-
-export { validator };
+export {
+	DecrementTime,
+	DeepFreeze,
+	Divide,
+	EnsureNumber,
+	Float,
+	IncrementTime,
+	IsNaN,
+	Multiply,
+	ONE_DAY,
+	ONE_HOUR,
+	ONE_MINUTE,
+	ONE_MONTH,
+	ONE_WEEK,
+	ONE_YEAR,
+	RemoveChars,
+	RemoveSpaces,
+	ReplaceChars,
+	StableStringify,
+	Stringify,
+	Subtract,
+	Sum,
+	ToDecimal,
+	ToLong,
+	ToPrecision,
+} from "./utils";

package/dist/kernel/{helpers → libs}/domain-classes.ts

@@ -1,7 +1,7 @@
-import { Iterator } from "../libs/iterator";
-import { Result } from "../libs/result";
+import { Iterator } from "../helpers/iterator";
 import type { IIterator } from "../types/iterator.types";
 import type { IResult } from "../types/result.types";
+import { Result } from "./result";
 
 /**
  * @description
@@ -10,7 +10,7 @@ import type { IResult } from "../types/result.types";
  * Contains both an iterator over each individual creation result and a combined
  * result that reflects the overall success or failure of the batch operation.
  */
-export interface CreateManyResult {
+interface CreateManyResult {
 	/**
 	 * @description
 	 * An iterator over each individual `Result` produced during the batch creation.

package/dist/kernel/libs/index.ts

@@ -1,5 +1,11 @@
 export { UUID } from "./crypto";
-export { Iterator } from "./iterator";
+export { DomainClasses } from "./domain-classes";
+export { DomainError } from "./domain-error";
 export { Result } from "./result";
 export { Utils } from "./utils";
 export { Validator } from "./validator";
+
+import utils from "./utils";
+import validator from "./validator";
+
+export { utils, validator };

package/dist/kernel/libs/result.ts

@@ -1,3 +1,4 @@
+import { Iterator } from "../helpers/iterator";
 import type { ICommand } from "../types/command.types";
 import type { IIterator } from "../types/iterator.types";
 import type {
@@ -8,7 +9,6 @@ import type {
 	IResultOption,
 } from "../types/result.types";
 import type { AnyObject } from "../types/utils.types";
-import { Iterator } from "./iterator";
 
 /**
  * @description

package/dist/kernel/libs/utils.ts

@@ -1,9 +1,14 @@
-import type { CalcOpt } from "../types/utils.types";
 import { DecrementTime, IncrementTime } from "../utils/date.utils";
 import { Divide, Multiply, Subtract, Sum } from "../utils/number.utils";
 import { RemoveChars, RemoveSpaces, ReplaceChars } from "../utils/string.utils";
 import validator, { type Validator } from "./validator";
 
+/**
+ * @description
+ * Options for calculations, such as specifying precision.
+ */
+type CalcOpt = { fractionDigits: number };
+
 /**
  * @description
  * Utility class providing various helper methods for date, number, and string manipulations.

package/dist/kernel/libs/validator.ts

@@ -1,4 +1,5 @@
 import type { Aggregate, Entity, ID, ValueObject } from "../core";
+import type { BaseSpecification } from "../core/specification";
 import type { AnyObject } from "../types/utils.types";
 import { Stringify } from "../utils/string.utils";
 
@@ -170,6 +171,18 @@ export class Validator {
 		);
 	}
 
+	/**
+	 * @description
+	 * Checks if the provided value is a `BaseSpecification` instance.
+	 *
+	 * @param props The value to check.
+	 * @returns True if the value is a Specification, false otherwise.
+	 */
+	public isSpecification(props: unknown): props is BaseSpecification<never> {
+		if (props === null || typeof props !== "object") return false;
+		return (props as AnyObject).__kind === "Specification";
+	}
+
 	/**
 	 * @description
 	 * Checks if the provided value is a symbol.

package/dist/kernel/types/command.types.ts

@@ -32,6 +32,4 @@ export interface IQuery<Input = void, Output = void> {
  * @template Input The input type.
  * @template Output The output type.
  */
-export type IUseCase<Input = void, Output = void> =
-	| ICommand<Input, Output>
-	| IQuery<Input, Output>;
+export type IUseCase<Input = void, Output = void> = ICommand<Input, Output>;

package/dist/kernel/types/index.ts

@@ -1,26 +1,6 @@
-export type {
-	Adapter,
-	IAdapter,
-} from "./adapter.types";
-
+export type { Adapter, IAdapter } from "./adapter.types";
 export type { ICommand, IQuery, IUseCase } from "./command.types";
-export type { IEntityProps, IEntitySettings } from "./entity.types";
-export type { IIterator, IIteratorConfig } from "./iterator.types";
-export type {
-	IResult,
-	IResultExecuteFn,
-	IResultHook,
-	IResultObject,
-	IResultOption,
-} from "./result.types";
-
+export type { DomainEvent, EventSubscriber, IEventBus } from "./event.types";
+export type { ISpecification } from "./specification.types";
 export type { UID } from "./uid.types";
-export type {
-	AnyObject,
-	BuiltIns,
-	CalcOpt,
-	Primitive,
-	ReadonlyDeep,
-} from "./utils.types";
-
-export type { IValueObjectSettings } from "./value-object.types";
+export type { AnyObject, ReadonlyDeep } from "./utils.types";

package/dist/kernel/types/specification.types.ts

@@ -0,0 +1,45 @@
+/**
+ * @description
+ * Core contract for the Specification pattern.
+ *
+ * A specification encapsulates a single named business rule that can be evaluated
+ * against a candidate object. The rule is reusable, composable, and lives in the
+ * domain layer — not scattered across use cases or services.
+ *
+ * @template T The type of the candidate being evaluated.
+ */
+export interface ISpecification<T> {
+	/**
+	 * @description
+	 * Evaluates whether the candidate satisfies this specification.
+	 *
+	 * @param candidate The domain object to evaluate.
+	 * @returns `true` if satisfied; `false` otherwise.
+	 */
+	isSatisfiedBy(candidate: T): boolean;
+
+	/**
+	 * @description
+	 * Returns a new specification that is satisfied only when **both** this and
+	 * the provided specification are satisfied (logical AND).
+	 *
+	 * @param other The specification to AND with.
+	 */
+	and(other: ISpecification<T>): ISpecification<T>;
+
+	/**
+	 * @description
+	 * Returns a new specification that is satisfied when **either** this or the
+	 * provided specification is satisfied (logical OR).
+	 *
+	 * @param other The specification to OR with.
+	 */
+	or(other: ISpecification<T>): ISpecification<T>;
+
+	/**
+	 * @description
+	 * Returns a new specification that is satisfied when this specification is
+	 * **not** satisfied (logical NOT).
+	 */
+	not(): ISpecification<T>;
+}

package/dist/kernel/types/utils.types.ts

@@ -8,13 +8,7 @@ export type AnyObject = Record<string, unknown>;
  * @description
  * Built-in types that are excluded from recursive transformations.
  */
-export type BuiltIns = Primitive | Date | RegExp;
-
-/**
- * @description
- * Options for calculations, such as specifying precision.
- */
-export type CalcOpt = { fractionDigits: number };
+type BuiltIns = Primitive | Date | RegExp;
 
 /**
  * @description
@@ -41,14 +35,7 @@ type HasMultipleCallSignatures<
  * @description
  * Primitive types that are not recursively transformed.
  */
-export type Primitive =
-	| null
-	| undefined
-	| string
-	| number
-	| boolean
-	| symbol
-	| bigint;
+type Primitive = null | undefined | string | number | boolean | symbol | bigint;
 
 /**
  * @description

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drimion",
-  "version": "0.1.12",
+  "version": "0.2.0",
   "description": "Headless DDD primitives CLI for TypeScript — own your domain",
   "keywords": [
     "ddd",