@c9up/atlas 0.1.3

package/src/decorators/entity.ts

@@ -0,0 +1,532 @@
+/**
+ * Entity decorators — @Entity, @Column, @PrimaryKey, @BelongsTo, @HasMany, @computed
+ *
+ * @implements FR29, FR30, stories 32.3, 32.4
+ */
+
+import "reflect-metadata";
+import {
+	COLUMN_SERIALIZE_KEY,
+	COMPUTED_KEY,
+	type ColumnSerializeConfig,
+} from "../BaseEntity.js";
+
+const ENTITY_KEY = Symbol("atlas:entity");
+const COLUMNS_KEY = Symbol("atlas:columns");
+const PRIMARY_KEY = Symbol("atlas:primary");
+const PRIMARY_KEY_GEN = Symbol("atlas:primary-gen");
+const RELATIONS_KEY = Symbol("atlas:relations");
+
+/** Auto-generation strategy for `@PrimaryKey({ generated: ... })`. */
+export type PrimaryKeyGenerator = "uuid";
+
+export interface PrimaryKeyOptions {
+	/**
+	 * Auto-generate the primary-key value on INSERT when the entity has none
+	 * (undefined). `'uuid'` produces an RFC-4122 v4 string via `crypto.randomUUID()`.
+	 * Default: no auto-generation — the column relies on a DB default
+	 * (`AUTOINCREMENT`, `SERIAL`, …) or the caller supplies a value.
+	 */
+	generated?: PrimaryKeyGenerator;
+}
+
+export interface EntityMetadata {
+	tableName: string;
+}
+
+/**
+ * Column adapter — the `{ prepare?, consume? }` callback pair shared between
+ * `@Column({ prepare, consume })` (entity columns) and `pivotColumnAdapters`
+ * (m2m pivot extras). Single source of truth for the adapter shape; both
+ * `ColumnOptions` and `ColumnMetadata` extend this interface.
+ */
+export interface ColumnAdapter {
+	/**
+	 * Transform the model value before it is persisted (model → DB). Mirror of
+	 * Adonis Lucid's `@column.prepare`.
+	 *
+	 * For entity columns, runs in `#entityToRow`, `#entityToRowPairs`,
+	 * `#plainToRowPairs`, `#update`, and `#buildSetPairs`. For m2m pivot extras
+	 * (`pivotColumnAdapters`), runs in the `attach()`/`sync()` row builder.
+	 *
+	 * **You MUST handle `null` and `undefined` yourself** — atlas calls the
+	 * callback unconditionally for every value, including null/undefined, so a
+	 * naive `(v: Decimal) => v.toString()` will throw on a null column. Return
+	 * `null` for null/undefined inputs to preserve nullable semantics.
+	 *
+	 * For pivot extras specifically: when `attach()` is called with
+	 * heterogeneous entries (the same extra key present on some entries and
+	 * absent on others), the absent entries back-fill the missing key as
+	 * `null` BEFORE `prepare` is called — your adapter must be null-safe even
+	 * when no caller wrote null explicitly on that row.
+	 *
+	 * MUST stay synchronous; the bind layer cannot await before handing values
+	 * to the Rust DML compiler. Returning a Promise throws.
+	 */
+	prepare?: (value: unknown) => unknown;
+	/**
+	 * Transform the raw DB value into the model attribute (DB → model). Mirror
+	 * of Adonis Lucid's `@column.consume`. For entity columns, runs in
+	 * `#hydrate`. For m2m pivot extras, runs in the `$extras.pivot_<col>`
+	 * projection (currently dormant — see `pivotColumnAdapters` JSDoc).
+	 *
+	 * **You MUST handle `null` and `undefined` yourself** — atlas calls the
+	 * callback unconditionally for every present row key, so a naive
+	 * `(v: string) => v.trim()` will throw on a null column. Return `null` for
+	 * null/undefined inputs to preserve nullable semantics.
+	 *
+	 * MUST stay synchronous (same constraint as `prepare`).
+	 */
+	consume?: (value: unknown) => unknown;
+}
+
+export interface ColumnMetadata extends ColumnAdapter {
+	propertyKey: string;
+	type?: string;
+	nullable?: boolean;
+	default?: unknown;
+	serializeAs?: string | null;
+	serialize?: (value: unknown) => unknown;
+}
+
+export interface ColumnOptions extends ColumnAdapter {
+	type?: string;
+	nullable?: boolean;
+	default?: unknown;
+	/** Rename this column at `toJSON` time. Use `null` to hide it entirely. */
+	serializeAs?: string | null;
+	/** Transform the value at `toJSON` time (e.g. mask a phone number, coerce a Date). */
+	serialize?: (value: unknown) => unknown;
+}
+
+type Constructor = new (...args: unknown[]) => unknown;
+
+export interface ManyToManyOptions {
+	/** Pivot table name joining the two sides (e.g., 'users_roles'). */
+	pivotTable: string;
+	/** Foreign key in the pivot table pointing to THIS entity (default: `${thisTable}_id`). */
+	foreignKey?: string;
+	/** Foreign key in the pivot table pointing to the RELATED entity (default: `${relatedTable}_id`). */
+	otherKey?: string;
+	/** Pivot extra columns to project into `$extras.pivot_<col>` on loaded relations (Story 31.8). */
+	pivotColumns?: string[];
+	/** Auto-write `created_at`/`updated_at` on `attach`/`sync` (Story 31.8). */
+	pivotTimestamps?:
+		| boolean
+		| { createdAt?: string | false; updatedAt?: string | false };
+	/**
+	 * Per-extra-column adapter map for typed pivot values. Mirrors
+	 * `@Column({ prepare, consume })` for entity columns: `prepare` runs on
+	 * every `attach()` / `sync()` write, before the value reaches the SQL bind
+	 * layer; `consume` runs on every load that projects the extra into
+	 * `$extras.pivot_<col>` (when the projection mechanism lands — currently
+	 * the load-side hook is dormant).
+	 *
+	 * Keys are pivot-row column names as written in the SQL (e.g. `amount`);
+	 * adapters are reused verbatim from `@c9up/atom/atlas` and friends so a
+	 * caller can pass `{ amount: decimalAtlasAdapter }` without wrapping.
+	 *
+	 * Adapters that are NOT listed here keep current pass-through behaviour
+	 * — backward compatible.
+	 */
+	pivotColumnAdapters?: Record<string, ColumnAdapter>;
+}
+
+/** Per-relation key/onQuery overrides (Story 31.3 + 31.4). */
+export interface RelationOptions {
+	/** Override the parent-side join column (default: parent PK). */
+	localKey?: string;
+	/** Override the child-side FK (default: `${parentSnake}_id` for hasOne/hasMany, `${relatedSnake}_id` on belongsTo parent row). */
+	foreignKey?: string;
+	/** `belongsTo` only — owner (target) side join column (default: related PK). */
+	ownerKey?: string;
+	/** Default constraint applied on every preload + lazy load (Story 31.4). */
+	onQuery?: (q: unknown) => void;
+	/** `toJSON()` key override — `null` hides the relation from serialization (Story 31.3). */
+	serializeAs?: string | null;
+}
+
+/** Configuration for `@HasOneThrough` / `@HasManyThrough` — two-hop relations (Story 31.2). */
+export interface ThroughOptions extends RelationOptions {
+	/** FK on the *intermediate* table that points at the parent (default: `${parentSnake}_id`). */
+	firstKey?: string;
+	/** FK on the *related* table that points at the intermediate (default: `${intermediateSnake}_id`). */
+	secondKey?: string;
+	/** Parent-side local join column (default: parent PK). */
+	localKey?: string;
+	/** Intermediate-side local join column matched by `secondKey` (default: intermediate PK). */
+	secondLocalKey?: string;
+}
+
+export interface RelationMetadata extends RelationOptions {
+	propertyKey: string;
+	type:
+		| "belongsTo"
+		| "hasOne"
+		| "hasMany"
+		| "hasOneThrough"
+		| "hasManyThrough"
+		| "manyToMany";
+	target: () => Constructor;
+	/** Intermediate ("through") model for two-hop relations — Story 31.2. */
+	through?: () => Constructor;
+	/** Extra through-specific keys. */
+	firstKey?: string;
+	secondKey?: string;
+	secondLocalKey?: string;
+	/** ManyToMany pivot configuration — required for type === 'manyToMany'. */
+	pivot?: ManyToManyOptions;
+}
+
+/** @Entity('table_name') — marks a class as a database entity. */
+export function Entity(tableName: string): ClassDecorator {
+	return (target) => {
+		Reflect.defineMetadata(ENTITY_KEY, { tableName }, target);
+	};
+}
+
+/** @Column() — marks a property as a database column. */
+export function Column(options?: ColumnOptions): PropertyDecorator {
+	return (target, propertyKey) => {
+		const columns: ColumnMetadata[] =
+			Reflect.getOwnMetadata(COLUMNS_KEY, target.constructor) ?? [];
+		const key = String(propertyKey);
+		// Deduplicate — @PrimaryKey also calls Column()
+		if (!columns.some((c) => c.propertyKey === key)) {
+			columns.push({
+				propertyKey: key,
+				type: options?.type,
+				nullable: options?.nullable,
+				default: options?.default,
+				serializeAs: options?.serializeAs,
+				serialize: options?.serialize,
+				prepare: options?.prepare,
+				consume: options?.consume,
+			});
+			Reflect.defineMetadata(COLUMNS_KEY, columns, target.constructor);
+		}
+
+		// Register serialize overrides on a separate map read by BaseEntity.toJSON.
+		// Stored per-class so subclasses can override a parent's serializeAs.
+		if (
+			options?.serializeAs !== undefined ||
+			options?.serialize !== undefined
+		) {
+			const serializeMap: Record<string, ColumnSerializeConfig> =
+				Reflect.getOwnMetadata(COLUMN_SERIALIZE_KEY, target.constructor) ?? {};
+			serializeMap[key] = {
+				serializeAs: options.serializeAs,
+				serialize: options.serialize,
+			};
+			Reflect.defineMetadata(
+				COLUMN_SERIALIZE_KEY,
+				serializeMap,
+				target.constructor,
+			);
+		}
+	};
+}
+
+/**
+ * @computed() — marks a getter as a computed column that shows up in `toJSON()`.
+ * The getter is NEVER read or written during persistence (it's derived from other
+ * real columns). Lucid-compatible alias.
+ *
+ * @implements Story 32.3
+ */
+export function computed(): MethodDecorator {
+	return (target, propertyKey) => {
+		const list: string[] =
+			Reflect.getOwnMetadata(COMPUTED_KEY, target.constructor) ?? [];
+		const key = String(propertyKey);
+		if (!list.includes(key)) {
+			list.push(key);
+			Reflect.defineMetadata(COMPUTED_KEY, list, target.constructor);
+		}
+	};
+}
+
+// ─── Date / DateTime column sub-decorators (story 32.8) ──────────
+
+export interface DateTimeColumnOptions extends ColumnOptions {
+	/** Set the column to `new Date()` on INSERT (like `created_at`). */
+	autoCreate?: boolean;
+	/** Set the column to `new Date()` on every UPDATE (like `updated_at`). */
+	autoUpdate?: boolean;
+}
+
+/** Symbol metadata key for per-column date-column config. Read by BaseRepository. */
+export const DATE_COLUMNS_KEY = Symbol.for("atlas:dateColumns");
+
+export interface DateColumnConfig {
+	/** `true` means the column holds date-only values (no time). */
+	dateOnly: boolean;
+	autoCreate?: boolean;
+	autoUpdate?: boolean;
+}
+
+function registerDateColumn(
+	target: object,
+	propertyKey: string | symbol,
+	config: DateColumnConfig,
+): void {
+	const ctor = (target as { constructor: object }).constructor;
+	const map: Record<string, DateColumnConfig> =
+		Reflect.getOwnMetadata(DATE_COLUMNS_KEY, ctor) ?? {};
+	map[String(propertyKey)] = config;
+	Reflect.defineMetadata(DATE_COLUMNS_KEY, map, ctor);
+}
+
+/**
+ * `@column.date()` — marks a property as a date-only column (YYYY-MM-DD).
+ * The raw DB value is hydrated to a JS Date; nulls pass through.
+ */
+function columnDate(options?: ColumnOptions): PropertyDecorator {
+	return (target, propertyKey) => {
+		Column(options)(target, propertyKey);
+		registerDateColumn(target, propertyKey, { dateOnly: true });
+	};
+}
+
+/**
+ * `@column.dateTime({ autoCreate, autoUpdate })` — marks a property as a
+ * timestamp column. Hydrated to JS Date on read.
+ *
+ * `autoCreate`: BaseRepository sets it to `new Date()` on INSERT.
+ * `autoUpdate`: BaseRepository sets it to `new Date()` on every UPDATE.
+ */
+function columnDateTime(options?: DateTimeColumnOptions): PropertyDecorator {
+	return (target, propertyKey) => {
+		Column(options)(target, propertyKey);
+		registerDateColumn(target, propertyKey, {
+			dateOnly: false,
+			autoCreate: options?.autoCreate,
+			autoUpdate: options?.autoUpdate,
+		});
+	};
+}
+
+/** Namespace access so users write `@column.date()` / `@column.dateTime()`. */
+const columnWithSubs = Column as typeof Column & {
+	date: typeof columnDate;
+	dateTime: typeof columnDateTime;
+};
+columnWithSubs.date = columnDate;
+columnWithSubs.dateTime = columnDateTime;
+
+/**
+ * `Column` exposed with its sub-decorators (`Column.date()`, `Column.dateTime()`).
+ * Alias exports so TS users can `import { column } from '@c9up/atlas'` for a
+ * Lucid-style lowercase naming when they prefer.
+ */
+export const column = Column as typeof Column & {
+	date: typeof columnDate;
+	dateTime: typeof columnDateTime;
+};
+
+/** Read the date-column configuration map for an entity class (walks prototype chain). */
+export function getDateColumnConfig(
+	entityClass: object,
+): Record<string, DateColumnConfig> {
+	const merged: Record<string, DateColumnConfig> = {};
+	let current: object | null = entityClass;
+	while (current && current !== Function.prototype) {
+		const map = Reflect.getOwnMetadata(DATE_COLUMNS_KEY, current) as
+			| Record<string, DateColumnConfig>
+			| undefined;
+		if (map) Object.assign(merged, map);
+		current = Object.getPrototypeOf(current);
+	}
+	return merged;
+}
+
+/** @PrimaryKey() — marks a property as the primary key. */
+export function PrimaryKey(options?: PrimaryKeyOptions): PropertyDecorator {
+	return (target, propertyKey) => {
+		Reflect.defineMetadata(
+			PRIMARY_KEY,
+			String(propertyKey),
+			target.constructor,
+		);
+		if (options?.generated) {
+			Reflect.defineMetadata(
+				PRIMARY_KEY_GEN,
+				options.generated,
+				target.constructor,
+			);
+		}
+		// Also register as a column
+		Column()(target, propertyKey);
+	};
+}
+
+/**
+ * Read the PK auto-generation strategy declared via `@PrimaryKey({ generated })`.
+ * Returns `undefined` when the entity's PK has no generator — caller-supplied
+ * or DB-defaulted.
+ */
+export function getPrimaryKeyGenerator(
+	entityClass: object,
+): PrimaryKeyGenerator | undefined {
+	let current: object | null = entityClass;
+	while (current && current !== Function.prototype) {
+		const gen = Reflect.getOwnMetadata(PRIMARY_KEY_GEN, current) as
+			| PrimaryKeyGenerator
+			| undefined;
+		if (gen) return gen;
+		current = Object.getPrototypeOf(current);
+	}
+	return undefined;
+}
+
+/** @BelongsTo(() => Related, { foreignKey, ownerKey, onQuery, serializeAs }) */
+export function BelongsTo(
+	target: () => Constructor,
+	options: RelationOptions = {},
+): PropertyDecorator {
+	return (proto, propertyKey) => {
+		addRelation(proto.constructor, {
+			propertyKey: String(propertyKey),
+			type: "belongsTo",
+			target,
+			...options,
+		});
+	};
+}
+
+/** @HasOne(() => Related, { localKey, foreignKey, onQuery, serializeAs }) */
+export function HasOne(
+	target: () => Constructor,
+	options: RelationOptions = {},
+): PropertyDecorator {
+	return (proto, propertyKey) => {
+		addRelation(proto.constructor, {
+			propertyKey: String(propertyKey),
+			type: "hasOne",
+			target,
+			...options,
+		});
+	};
+}
+
+/** @HasMany(() => Related, { localKey, foreignKey, onQuery, serializeAs }) */
+export function HasMany(
+	target: () => Constructor,
+	options: RelationOptions = {},
+): PropertyDecorator {
+	return (proto, propertyKey) => {
+		addRelation(proto.constructor, {
+			propertyKey: String(propertyKey),
+			type: "hasMany",
+			target,
+			...options,
+		});
+	};
+}
+
+/** @HasOneThrough(() => Related, () => Through, { firstKey, secondKey, localKey, secondLocalKey, onQuery }) */
+export function HasOneThrough(
+	target: () => Constructor,
+	through: () => Constructor,
+	options: ThroughOptions = {},
+): PropertyDecorator {
+	return (proto, propertyKey) => {
+		addRelation(proto.constructor, {
+			propertyKey: String(propertyKey),
+			type: "hasOneThrough",
+			target,
+			through,
+			...options,
+		});
+	};
+}
+
+/** @HasManyThrough(() => Related, () => Through, { firstKey, secondKey, localKey, secondLocalKey, onQuery }) */
+export function HasManyThrough(
+	target: () => Constructor,
+	through: () => Constructor,
+	options: ThroughOptions = {},
+): PropertyDecorator {
+	return (proto, propertyKey) => {
+		addRelation(proto.constructor, {
+			propertyKey: String(propertyKey),
+			type: "hasManyThrough",
+			target,
+			through,
+			...options,
+		});
+	};
+}
+
+/** @ManyToMany(() => Related, { pivotTable: 'users_roles' }) */
+export function ManyToMany(
+	target: () => Constructor,
+	options: ManyToManyOptions & RelationOptions,
+): PropertyDecorator {
+	return (proto, propertyKey) => {
+		addRelation(proto.constructor, {
+			propertyKey: String(propertyKey),
+			type: "manyToMany",
+			target,
+			pivot: options,
+			onQuery: options.onQuery,
+			serializeAs: options.serializeAs,
+		});
+	};
+}
+
+function addRelation(target: object, relation: RelationMetadata): void {
+	const relations: RelationMetadata[] =
+		Reflect.getOwnMetadata(RELATIONS_KEY, target) ?? [];
+	relations.push(relation);
+	Reflect.defineMetadata(RELATIONS_KEY, relations, target);
+}
+
+/** Get entity metadata for a class. */
+export function getEntityMetadata(
+	target: Constructor,
+): EntityMetadata | undefined {
+	return Reflect.getMetadata(ENTITY_KEY, target);
+}
+
+/** Get column metadata for a class (returns a copy). */
+export function getColumnMetadata(target: Constructor): ColumnMetadata[] {
+	return [...(Reflect.getMetadata(COLUMNS_KEY, target) ?? [])];
+}
+
+/** Get primary key property name. */
+export function getPrimaryKey(target: Constructor): string | undefined {
+	return Reflect.getMetadata(PRIMARY_KEY, target);
+}
+
+/** Get relation metadata for a class (returns a copy). */
+export function getRelationMetadata(target: Constructor): RelationMetadata[] {
+	return [...(Reflect.getMetadata(RELATIONS_KEY, target) ?? [])];
+}
+
+// ─── Soft Deletes ────────────────────────────────────────────
+
+const SOFT_DELETE_KEY = Symbol("atlas:softDeletes");
+
+/** @SoftDeletes() — marks entity as soft-deletable via deleted_at column. */
+export function SoftDeletes(): ClassDecorator {
+	return (target) => {
+		Reflect.defineMetadata(SOFT_DELETE_KEY, true, target);
+		// Auto-add deleted_at as a column
+		const columns: ColumnMetadata[] =
+			Reflect.getOwnMetadata(COLUMNS_KEY, target) ?? [];
+		if (!columns.some((c) => c.propertyKey === "deletedAt")) {
+			columns.push({
+				propertyKey: "deletedAt",
+				type: "timestamp",
+				nullable: true,
+			});
+			Reflect.defineMetadata(COLUMNS_KEY, columns, target);
+		}
+	};
+}
+
+/** Check if an entity class uses soft deletes. */
+export function hasSoftDeletes(target: Constructor): boolean {
+	return Reflect.getMetadata(SOFT_DELETE_KEY, target) === true;
+}

package/src/decorators/hooks.ts

@@ -0,0 +1,169 @@
+/**
+ * Lifecycle hook decorators — Lucid-compatible hook surface.
+ *
+ * Decorate a static method on an entity with one of the hooks below; Atlas
+ * fires it at the matching point in the BaseRepository CRUD pipeline. Hooks
+ * are inherited from the prototype chain — a hook on a parent entity also
+ * fires for subclasses.
+ *
+ *     class User extends BaseEntity {
+ *       @beforeSave()
+ *       static async hashPassword(user: User) {
+ *         if (user.isDirty('password')) {
+ *           user.password = await hash(user.password)
+ *         }
+ *       }
+ *     }
+ *
+ * @implements Story 32.1
+ */
+
+import "reflect-metadata";
+import type { BaseEntity } from "../BaseEntity.js";
+import type { ModelQuery } from "../ModelQuery.js";
+
+/** All hook kinds Atlas supports — mirrors Lucid's surface. */
+export type HookKind =
+	| "beforeSave"
+	| "afterSave"
+	| "beforeCreate"
+	| "afterCreate"
+	| "beforeUpdate"
+	| "afterUpdate"
+	| "beforeDelete"
+	| "afterDelete"
+	| "beforeFind"
+	| "afterFind"
+	| "beforeFetch"
+	| "afterFetch"
+	| "beforePaginate"
+	| "afterPaginate";
+
+/** Argument shape for each hook kind. */
+export interface HookArgs {
+	beforeSave: BaseEntity;
+	afterSave: BaseEntity;
+	beforeCreate: BaseEntity;
+	afterCreate: BaseEntity;
+	beforeUpdate: BaseEntity;
+	afterUpdate: BaseEntity;
+	beforeDelete: BaseEntity;
+	afterDelete: BaseEntity;
+	beforeFind: ModelQuery<BaseEntity>;
+	afterFind: BaseEntity | null;
+	beforeFetch: ModelQuery<BaseEntity>;
+	afterFetch: BaseEntity[];
+	beforePaginate: ModelQuery<BaseEntity>;
+	afterPaginate: BaseEntity[];
+}
+
+/** A hook handler is a static function that receives the kind-specific arg. */
+export type HookHandler<K extends HookKind = HookKind> = (
+	arg: HookArgs[K],
+) => void | Promise<void>;
+
+const HOOKS_KEY = Symbol.for("atlas:hooks");
+
+/** Per-entity-class store: kind → handlers. Walked at fire time across the prototype chain. */
+type HookRegistry = Partial<Record<HookKind, HookHandler[]>>;
+
+function getOwnRegistry(target: object): HookRegistry {
+	const existing: unknown = Reflect.getOwnMetadata(HOOKS_KEY, target);
+	if (isHookRegistry(existing)) return existing;
+	const registry: HookRegistry = {};
+	Reflect.defineMetadata(HOOKS_KEY, registry, target);
+	return registry;
+}
+
+function isHookRegistry(value: unknown): value is HookRegistry {
+	if (typeof value !== "object" || value === null) return false;
+	for (const v of Object.values(value)) {
+		if (v !== undefined && !Array.isArray(v)) return false;
+	}
+	return true;
+}
+
+function isHookHandler(value: unknown): value is HookHandler {
+	return typeof value === "function";
+}
+
+/** Register a static method on the class as a hook handler. */
+function register(kind: HookKind): MethodDecorator {
+	return (target, propertyKey) => {
+		// target is the constructor for static methods, the prototype for instance methods
+		const ctor = typeof target === "function" ? target : target.constructor;
+		const handler: unknown = Reflect.get(ctor, propertyKey);
+		if (!isHookHandler(handler)) {
+			throw new Error(
+				`@${kind} must decorate a static method, got ${String(propertyKey)}`,
+			);
+		}
+		const registry = getOwnRegistry(ctor);
+		if (!registry[kind]) registry[kind] = [];
+		registry[kind]?.push(handler);
+	};
+}
+
+// ─── Decorators (one per hook kind) ───────────────────────────
+
+export const beforeSave = (): MethodDecorator => register("beforeSave");
+export const afterSave = (): MethodDecorator => register("afterSave");
+export const beforeCreate = (): MethodDecorator => register("beforeCreate");
+export const afterCreate = (): MethodDecorator => register("afterCreate");
+export const beforeUpdate = (): MethodDecorator => register("beforeUpdate");
+export const afterUpdate = (): MethodDecorator => register("afterUpdate");
+export const beforeDelete = (): MethodDecorator => register("beforeDelete");
+export const afterDelete = (): MethodDecorator => register("afterDelete");
+export const beforeFind = (): MethodDecorator => register("beforeFind");
+export const afterFind = (): MethodDecorator => register("afterFind");
+export const beforeFetch = (): MethodDecorator => register("beforeFetch");
+export const afterFetch = (): MethodDecorator => register("afterFetch");
+export const beforePaginate = (): MethodDecorator => register("beforePaginate");
+export const afterPaginate = (): MethodDecorator => register("afterPaginate");
+
+/**
+ * Walk the prototype chain and collect every handler registered for `kind`.
+ * Parent-class hooks fire BEFORE child-class hooks (so a base entity can set
+ * up scoping that the child then refines).
+ */
+export function collectHooks<K extends HookKind>(
+	entityClass: new (...args: unknown[]) => BaseEntity,
+	kind: K,
+): HookHandler<K>[] {
+	const handlers: HookHandler<K>[] = [];
+	let ctor: object | null = entityClass;
+	const chain: object[] = [];
+	while (
+		ctor &&
+		ctor !== Function.prototype &&
+		(ctor as { name?: string }).name
+	) {
+		chain.push(ctor);
+		ctor = Object.getPrototypeOf(ctor);
+	}
+	// Walk parent → child so the most-base hook fires first
+	for (const c of chain.reverse()) {
+		const registry = Reflect.getOwnMetadata(HOOKS_KEY, c) as
+			| HookRegistry
+			| undefined;
+		const list = registry?.[kind] as HookHandler<K>[] | undefined;
+		if (list) handlers.push(...list);
+	}
+	return handlers;
+}
+
+/**
+ * Fire every handler for `kind` sequentially. Awaits each one so a hook can
+ * mutate the entity before the next hook (or the persistence step) sees it.
+ * If any hook throws, the whole operation aborts and the error propagates.
+ */
+export async function fireHooks<K extends HookKind>(
+	entityClass: new (...args: unknown[]) => BaseEntity,
+	kind: K,
+	arg: HookArgs[K],
+): Promise<void> {
+	const handlers = collectHooks(entityClass, kind);
+	for (const handler of handlers) {
+		await handler(arg);
+	}
+}