@c9up/atlas 0.1.3 → 0.1.5

package/dist/decorators/entity.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Entity decorators — @Entity, @Column, @PrimaryKey, @BelongsTo, @HasMany, @computed
+ *
+ * @implements FR29, FR30, stories 32.3, 32.4
+ */
+import "reflect-metadata";
+/** 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 declare function Entity(tableName: string): ClassDecorator;
+/** @Column() — marks a property as a database column. */
+export declare function Column(options?: ColumnOptions): PropertyDecorator;
+/**
+ * @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 declare function computed(): MethodDecorator;
+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 declare const DATE_COLUMNS_KEY: unique symbol;
+export interface DateColumnConfig {
+    /** `true` means the column holds date-only values (no time). */
+    dateOnly: boolean;
+    autoCreate?: boolean;
+    autoUpdate?: boolean;
+}
+/**
+ * `@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.
+ */
+declare function columnDate(options?: ColumnOptions): PropertyDecorator;
+/**
+ * `@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.
+ */
+declare function columnDateTime(options?: DateTimeColumnOptions): PropertyDecorator;
+/**
+ * `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 declare const column: typeof Column & {
+    date: typeof columnDate;
+    dateTime: typeof columnDateTime;
+};
+/** Read the date-column configuration map for an entity class (walks prototype chain). */
+export declare function getDateColumnConfig(entityClass: object): Record<string, DateColumnConfig>;
+/** @PrimaryKey() — marks a property as the primary key. */
+export declare function PrimaryKey(options?: PrimaryKeyOptions): PropertyDecorator;
+/**
+ * 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 declare function getPrimaryKeyGenerator(entityClass: object): PrimaryKeyGenerator | undefined;
+/** @BelongsTo(() => Related, { foreignKey, ownerKey, onQuery, serializeAs }) */
+export declare function BelongsTo(target: () => Constructor, options?: RelationOptions): PropertyDecorator;
+/** @HasOne(() => Related, { localKey, foreignKey, onQuery, serializeAs }) */
+export declare function HasOne(target: () => Constructor, options?: RelationOptions): PropertyDecorator;
+/** @HasMany(() => Related, { localKey, foreignKey, onQuery, serializeAs }) */
+export declare function HasMany(target: () => Constructor, options?: RelationOptions): PropertyDecorator;
+/** @HasOneThrough(() => Related, () => Through, { firstKey, secondKey, localKey, secondLocalKey, onQuery }) */
+export declare function HasOneThrough(target: () => Constructor, through: () => Constructor, options?: ThroughOptions): PropertyDecorator;
+/** @HasManyThrough(() => Related, () => Through, { firstKey, secondKey, localKey, secondLocalKey, onQuery }) */
+export declare function HasManyThrough(target: () => Constructor, through: () => Constructor, options?: ThroughOptions): PropertyDecorator;
+/** @ManyToMany(() => Related, { pivotTable: 'users_roles' }) */
+export declare function ManyToMany(target: () => Constructor, options: ManyToManyOptions & RelationOptions): PropertyDecorator;
+/** Get entity metadata for a class. */
+export declare function getEntityMetadata(target: Constructor): EntityMetadata | undefined;
+/** Get column metadata for a class (returns a copy). */
+export declare function getColumnMetadata(target: Constructor): ColumnMetadata[];
+/** Get primary key property name. */
+export declare function getPrimaryKey(target: Constructor): string | undefined;
+/** Get relation metadata for a class (returns a copy). */
+export declare function getRelationMetadata(target: Constructor): RelationMetadata[];
+/** @SoftDeletes() — marks entity as soft-deletable via deleted_at column. */
+export declare function SoftDeletes(): ClassDecorator;
+/** Check if an entity class uses soft deletes. */
+export declare function hasSoftDeletes(target: Constructor): boolean;
+export {};
+//# sourceMappingURL=entity.d.ts.map

package/dist/decorators/entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../src/decorators/entity.ts"],"names":[],"mappings":"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"}

package/dist/decorators/entity.js

@@ -0,0 +1,264 @@
+/**
+ * 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, } 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");
+/** @Entity('table_name') — marks a class as a database entity. */
+export function Entity(tableName) {
+    return (target) => {
+        Reflect.defineMetadata(ENTITY_KEY, { tableName }, target);
+    };
+}
+/** @Column() — marks a property as a database column. */
+export function Column(options) {
+    return (target, propertyKey) => {
+        const columns = 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 = 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() {
+    return (target, propertyKey) => {
+        const list = Reflect.getOwnMetadata(COMPUTED_KEY, target.constructor) ?? [];
+        const key = String(propertyKey);
+        if (!list.includes(key)) {
+            list.push(key);
+            Reflect.defineMetadata(COMPUTED_KEY, list, target.constructor);
+        }
+    };
+}
+/** Symbol metadata key for per-column date-column config. Read by BaseRepository. */
+export const DATE_COLUMNS_KEY = Symbol.for("atlas:dateColumns");
+function registerDateColumn(target, propertyKey, config) {
+    const ctor = target.constructor;
+    const map = 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) {
+    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) {
+    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;
+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;
+/** Read the date-column configuration map for an entity class (walks prototype chain). */
+export function getDateColumnConfig(entityClass) {
+    const merged = {};
+    let current = entityClass;
+    while (current && current !== Function.prototype) {
+        const map = Reflect.getOwnMetadata(DATE_COLUMNS_KEY, current);
+        if (map)
+            Object.assign(merged, map);
+        current = Object.getPrototypeOf(current);
+    }
+    return merged;
+}
+/** @PrimaryKey() — marks a property as the primary key. */
+export function PrimaryKey(options) {
+    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) {
+    let current = entityClass;
+    while (current && current !== Function.prototype) {
+        const gen = Reflect.getOwnMetadata(PRIMARY_KEY_GEN, current);
+        if (gen)
+            return gen;
+        current = Object.getPrototypeOf(current);
+    }
+    return undefined;
+}
+/** @BelongsTo(() => Related, { foreignKey, ownerKey, onQuery, serializeAs }) */
+export function BelongsTo(target, options = {}) {
+    return (proto, propertyKey) => {
+        addRelation(proto.constructor, {
+            propertyKey: String(propertyKey),
+            type: "belongsTo",
+            target,
+            ...options,
+        });
+    };
+}
+/** @HasOne(() => Related, { localKey, foreignKey, onQuery, serializeAs }) */
+export function HasOne(target, options = {}) {
+    return (proto, propertyKey) => {
+        addRelation(proto.constructor, {
+            propertyKey: String(propertyKey),
+            type: "hasOne",
+            target,
+            ...options,
+        });
+    };
+}
+/** @HasMany(() => Related, { localKey, foreignKey, onQuery, serializeAs }) */
+export function HasMany(target, options = {}) {
+    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, through, options = {}) {
+    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, through, options = {}) {
+    return (proto, propertyKey) => {
+        addRelation(proto.constructor, {
+            propertyKey: String(propertyKey),
+            type: "hasManyThrough",
+            target,
+            through,
+            ...options,
+        });
+    };
+}
+/** @ManyToMany(() => Related, { pivotTable: 'users_roles' }) */
+export function ManyToMany(target, options) {
+    return (proto, propertyKey) => {
+        addRelation(proto.constructor, {
+            propertyKey: String(propertyKey),
+            type: "manyToMany",
+            target,
+            pivot: options,
+            onQuery: options.onQuery,
+            serializeAs: options.serializeAs,
+        });
+    };
+}
+function addRelation(target, relation) {
+    const relations = Reflect.getOwnMetadata(RELATIONS_KEY, target) ?? [];
+    relations.push(relation);
+    Reflect.defineMetadata(RELATIONS_KEY, relations, target);
+}
+/** Get entity metadata for a class. */
+export function getEntityMetadata(target) {
+    return Reflect.getMetadata(ENTITY_KEY, target);
+}
+/** Get column metadata for a class (returns a copy). */
+export function getColumnMetadata(target) {
+    return [...(Reflect.getMetadata(COLUMNS_KEY, target) ?? [])];
+}
+/** Get primary key property name. */
+export function getPrimaryKey(target) {
+    return Reflect.getMetadata(PRIMARY_KEY, target);
+}
+/** Get relation metadata for a class (returns a copy). */
+export function getRelationMetadata(target) {
+    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() {
+    return (target) => {
+        Reflect.defineMetadata(SOFT_DELETE_KEY, true, target);
+        // Auto-add deleted_at as a column
+        const columns = 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) {
+    return Reflect.getMetadata(SOFT_DELETE_KEY, target) === true;
+}
+//# sourceMappingURL=entity.js.map

package/dist/decorators/entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.js","sourceRoot":"","sources":["../../src/decorators/entity.ts"],"names":[],"mappings":"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"}

package/dist/decorators/hooks.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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>;
+export declare const beforeSave: () => MethodDecorator;
+export declare const afterSave: () => MethodDecorator;
+export declare const beforeCreate: () => MethodDecorator;
+export declare const afterCreate: () => MethodDecorator;
+export declare const beforeUpdate: () => MethodDecorator;
+export declare const afterUpdate: () => MethodDecorator;
+export declare const beforeDelete: () => MethodDecorator;
+export declare const afterDelete: () => MethodDecorator;
+export declare const beforeFind: () => MethodDecorator;
+export declare const afterFind: () => MethodDecorator;
+export declare const beforeFetch: () => MethodDecorator;
+export declare const afterFetch: () => MethodDecorator;
+export declare const beforePaginate: () => MethodDecorator;
+export declare const afterPaginate: () => MethodDecorator;
+/**
+ * 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 declare function collectHooks<K extends HookKind>(entityClass: new (...args: unknown[]) => BaseEntity, kind: K): HookHandler<K>[];
+/**
+ * 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 declare function fireHooks<K extends HookKind>(entityClass: new (...args: unknown[]) => BaseEntity, kind: K, arg: HookArgs[K]): Promise<void>;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/decorators/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/decorators/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,+DAA+D;AAC/D,MAAM,MAAM,QAAQ,GACjB,YAAY,GACZ,WAAW,GACX,cAAc,GACd,aAAa,GACb,cAAc,GACd,aAAa,GACb,cAAc,GACd,aAAa,GACb,YAAY,GACZ,WAAW,GACX,aAAa,GACb,YAAY,GACZ,gBAAgB,GAChB,eAAe,CAAC;AAEnB,yCAAyC;AACzC,MAAM,WAAW,QAAQ;IACxB,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,UAAU,CAAC;IACtB,YAAY,EAAE,UAAU,CAAC;IACzB,WAAW,EAAE,UAAU,CAAC;IACxB,YAAY,EAAE,UAAU,CAAC;IACzB,WAAW,EAAE,UAAU,CAAC;IACxB,YAAY,EAAE,UAAU,CAAC;IACzB,WAAW,EAAE,UAAU,CAAC;IACxB,UAAU,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;IACnC,SAAS,EAAE,UAAU,GAAG,IAAI,CAAC;IAC7B,WAAW,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;IACpC,UAAU,EAAE,UAAU,EAAE,CAAC;IACzB,cAAc,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;IACvC,aAAa,EAAE,UAAU,EAAE,CAAC;CAC5B;AAED,+EAA+E;AAC/E,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,IAAI,CACxD,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,KACZ,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AA8C1B,eAAO,MAAM,UAAU,QAAO,eAAyC,CAAC;AACxE,eAAO,MAAM,SAAS,QAAO,eAAwC,CAAC;AACtE,eAAO,MAAM,YAAY,QAAO,eAA2C,CAAC;AAC5E,eAAO,MAAM,WAAW,QAAO,eAA0C,CAAC;AAC1E,eAAO,MAAM,YAAY,QAAO,eAA2C,CAAC;AAC5E,eAAO,MAAM,WAAW,QAAO,eAA0C,CAAC;AAC1E,eAAO,MAAM,YAAY,QAAO,eAA2C,CAAC;AAC5E,eAAO,MAAM,WAAW,QAAO,eAA0C,CAAC;AAC1E,eAAO,MAAM,UAAU,QAAO,eAAyC,CAAC;AACxE,eAAO,MAAM,SAAS,QAAO,eAAwC,CAAC;AACtE,eAAO,MAAM,WAAW,QAAO,eAA0C,CAAC;AAC1E,eAAO,MAAM,UAAU,QAAO,eAAyC,CAAC;AACxE,eAAO,MAAM,cAAc,QAAO,eAA6C,CAAC;AAChF,eAAO,MAAM,aAAa,QAAO,eAA4C,CAAC;AAE9E;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,QAAQ,EAC9C,WAAW,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,UAAU,EACnD,IAAI,EAAE,CAAC,GACL,WAAW,CAAC,CAAC,CAAC,EAAE,CAqBlB;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,CAAC,SAAS,QAAQ,EACjD,WAAW,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,UAAU,EACnD,IAAI,EAAE,CAAC,EACP,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,GACd,OAAO,CAAC,IAAI,CAAC,CAKf"}