@gravito/echo 3.0.0 → 3.1.0

package/dist/atlas/src/orm/model/concerns/HasPersistence.d.ts

@@ -0,0 +1,87 @@
+/**
+ * HasPersistence Concern
+ * @description Provides database persistence functionality including saving, deleting, and refreshing.
+ */
+export declare class HasPersistence {
+    /**
+     * Indicates if the model exists in the database.
+     * @internal
+     */
+    protected _exists: boolean;
+    /**
+     * Check if the model instance exists in the database.
+     *
+     * @returns True if the model has been persisted
+     */
+    get exists(): boolean;
+    /**
+     * Save the model instance to the database (insert or update).
+     *
+     * @returns A promise that resolves to the model instance
+     *
+     * @example
+     * ```typescript
+     * await user.save()
+     * ```
+     */
+    save(): Promise<this>;
+    /**
+     * Perform an insert operation for a new model instance.
+     *
+     * @returns A promise that resolves to the model instance
+     * @internal
+     */
+    protected _performInsert(): Promise<this>;
+    /**
+     * Perform an update operation for an existing model instance.
+     *
+     * @returns A promise that resolves to the model instance
+     * @internal
+     */
+    protected _performUpdate(): Promise<this>;
+    /**
+     * Delete the model instance from the database.
+     * Supports soft deletes if configured on the model.
+     *
+     * @returns A promise that resolves to true if deleted successfully
+     *
+     * @example
+     * ```typescript
+     * await user.delete()
+     * ```
+     */
+    delete(): Promise<boolean>;
+    /**
+     * Restore a soft-deleted model instance.
+     *
+     * @returns A promise that resolves to true
+     *
+     * @example
+     * ```typescript
+     * await user.restore()
+     * ```
+     */
+    restore(): Promise<boolean>;
+    /**
+     * Force a hard delete even if soft deletes are enabled.
+     *
+     * @returns A promise that resolves to true
+     *
+     * @example
+     * ```typescript
+     * await user.forceDelete()
+     * ```
+     */
+    forceDelete(): Promise<boolean>;
+    /**
+     * Refresh the model instance with fresh data from the database.
+     *
+     * @returns A promise that resolves to the model instance
+     *
+     * @example
+     * ```typescript
+     * await user.refresh()
+     * ```
+     */
+    refresh(): Promise<this>;
+}

package/dist/atlas/src/orm/model/concerns/HasRelationships.d.ts

@@ -0,0 +1,117 @@
+import type { Model, ModelConstructor } from '../Model';
+/**
+ * HasRelationships Concern
+ * @description Provides relationship management functionality including defining and loading relationships.
+ */
+export declare class HasRelationships {
+    /**
+     * Define a one-to-many relationship.
+     * Returns a QueryBuilder scoped to the related records.
+     *
+     * @template R - The related model type.
+     * @param related - The related model constructor.
+     * @param foreignKey - The foreign key on the related table.
+     * @param localKey - The local key on this table.
+     * @returns A QueryBuilder for the related model.
+     * @example
+     * ```typescript
+     * const posts = await user.hasMany(Post).where('published', true).get()
+     * ```
+     */
+    hasMany<R extends Model>(related: ModelConstructor<R> & typeof Model, foreignKey?: string, localKey?: string): any;
+    /**
+     * Define a one-to-one relationship.
+     *
+     * @template R - The related model type.
+     * @param related - The related model constructor.
+     * @param foreignKey - The foreign key on the related table.
+     * @param localKey - The local key on this table.
+     * @returns A QueryBuilder for the related model, limited to 1 result.
+     */
+    hasOne<R extends Model>(related: ModelConstructor<R> & typeof Model, foreignKey?: string, localKey?: string): any;
+    /**
+     * Define an inverse one-to-one or one-to-many relationship.
+     *
+     * @template R - The related model type.
+     * @param related - The related model constructor.
+     * @param foreignKey - The foreign key on this table.
+     * @param ownerKey - The owner key on the related table.
+     * @returns A QueryBuilder for the related model.
+     * @example
+     * ```typescript
+     * const user = await post.belongsTo(User).first()
+     * ```
+     */
+    belongsTo<R extends Model>(related: ModelConstructor<R> & typeof Model, foreignKey?: string, ownerKey?: string): any;
+    /**
+     * Define a many-to-many relationship through a pivot table.
+     *
+     * @template R - The related model type.
+     * @param related - The related model constructor.
+     * @param pivotTable - The name of the join table.
+     * @param foreignPivotKey - The key on the pivot table pointing to this model.
+     * @param relatedPivotKey - The key on the pivot table pointing to the related model.
+     * @param localKey - The local key on this table.
+     * @param relatedKey - The related key on the related table.
+     * @returns Promise resolving to an array of related models.
+     */
+    belongsToMany<R extends Model>(related: ModelConstructor<R> & typeof Model, pivotTable: string, foreignPivotKey?: string, relatedPivotKey?: string, localKey?: string, relatedKey?: string): Promise<R[]>;
+    /**
+     * Stream hasMany relationship with cursor-based iteration
+     * Memory-safe for large relationship sets
+     *
+     * @example
+     * ```typescript
+     * for await (const posts of user.hasManyStream(Post, 'user_id', 100)) {
+     *   for (const post of posts) {
+     *     await processPost(post)
+     *   }
+     * }
+     * ```
+     */
+    hasManyStream<R extends Model>(related: ModelConstructor<R> & typeof Model, foreignKey?: string, chunkSize?: number, localKey?: string): AsyncGenerator<R[], void, unknown>;
+    /**
+     * Define a polymorphic one-to-one relationship.
+     *
+     * @template R - The related model type.
+     * @param related - The related model constructor.
+     * @param name - The polymorphic relationship name (used to derive type and id fields).
+     * @param foreignKey - Optional explicit foreign key.
+     * @param localKey - Optional explicit local key.
+     * @returns A QueryBuilder for the related model.
+     */
+    morphOne<R extends Model>(related: ModelConstructor<R> & typeof Model, name: string, foreignKey?: string, localKey?: string): any;
+    /**
+     * Define a polymorphic one-to-many relationship.
+     *
+     * @template R - The related model type.
+     * @param related - The related model constructor.
+     * @param name - The polymorphic relationship name.
+     * @param foreignKey - Optional explicit foreign key.
+     * @param localKey - Optional explicit local key.
+     * @returns A QueryBuilder for the related model.
+     */
+    morphMany<R extends Model>(related: ModelConstructor<R> & typeof Model, name: string, foreignKey?: string, localKey?: string): any;
+    /**
+     * Define a polymorphic inverse relationship.
+     *
+     * @template R - The related model type.
+     * @param name - The polymorphic relationship name.
+     * @param typeField - Optional explicit type field name.
+     * @param idField - Optional explicit ID field name.
+     * @returns A QueryBuilder for the resolved related model, or null if not resolvable.
+     */
+    morphTo<R extends Model>(name: string, typeField?: string, idField?: string): any;
+    /**
+     * Lazy load relationships for the current model
+     * @example await user.load('posts')
+     */
+    load(relation: string | string[]): Promise<this>;
+    /**
+     * Alias for load(), used for fluent eager loading on an instance.
+     *
+     * @param relation - The relationship name or an array of names
+     * @returns A promise that resolves to the model instance
+     */
+    with(relation: string | string[]): Promise<this>;
+}

package/dist/atlas/src/orm/model/concerns/HasSerialization.d.ts

@@ -0,0 +1,64 @@
+/**
+ * HasSerialization Concern
+ * @description Provides serialization functionality including converting to JSON, array/object, and handling hidden/appended attributes.
+ */
+export declare class HasSerialization {
+    /**
+     * Fill the model instance with an object of attributes.
+     *
+     * @param attributes - Key-value pairs of attributes to set
+     * @returns The model instance
+     *
+     * @example
+     * ```typescript
+     * user.fill({ name: 'Carl', email: 'carl@example.com' })
+     * ```
+     */
+    fill(attributes: Record<string, unknown>): this;
+    /**
+     * Convert the model instance to a JSON string.
+     *
+     * @returns A JSON string representation of the model
+     *
+     * @example
+     * ```typescript
+     * const json = user.toJSON()
+     * ```
+     */
+    toJSON(): unknown;
+    /**
+     * Convert the model instance to a plain JavaScript object.
+     * Alias for `toJSON()`.
+     *
+     * @returns A plain object representation of the model
+     */
+    toObject(): Record<string, unknown>;
+    /**
+     * Convert the model instance to a plain JavaScript object.
+     * Alias for `toJSON()`.
+     *
+     * @returns A plain object representation of the model
+     */
+    toArray(): Record<string, unknown>;
+    /**
+     * Get all attributes currently set on the model.
+     *
+     * @returns An object containing all model attributes
+     * @internal
+     */
+    getAttributes(): Record<string, unknown>;
+    /**
+     * Get a specific attribute value.
+     *
+     * @param key - The attribute name
+     * @returns The attribute value
+     * @internal
+     */
+    getAttribute(key: string): unknown;
+    /**
+     * Get the string representation of the model.
+     *
+     * @returns A JSON string representation of the model
+     */
+    toString(): string;
+}

package/dist/atlas/src/orm/model/concerns/applyMixins.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Mixin utility for composing classes with multiple concerns.
+ * @description Utility function to copy properties from mixin prototypes to a base class prototype.
+ *
+ * @param base - Base class to extend
+ * @param mixins - Mixin classes to apply
+ * @returns Combined class with all mixin properties
+ *
+ * @example
+ * ```typescript
+ * class MyModel extends Model {}
+ * applyMixins(MyModel, [HasAttributes, HasEvents])
+ * ```
+ */
+export declare function applyMixins<T extends new (...args: unknown[]) => unknown, U extends (new (...args: unknown[]) => unknown)[]>(base: T, mixins: U): T & U[number];

package/dist/atlas/src/orm/model/concerns/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Concerns Index
+ *
+ * Re-exports all model concerns for easier importing.
+ */
+export { applyMixins } from './applyMixins';
+export type { ModelAttributes } from './HasAttributes';
+export { HasAttributes } from './HasAttributes';
+export { HasEvents } from './HasEvents';
+export { HasPersistence } from './HasPersistence';
+export { HasRelationships } from './HasRelationships';
+export { HasSerialization } from './HasSerialization';

package/dist/atlas/src/orm/model/decorators.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Options for the SoftDeletes decorator.
+ */
+export interface SoftDeletesOptions {
+    /**
+     * The name of the column used to store the deletion timestamp.
+     * @default 'deleted_at'
+     */
+    column?: string;
+}
+/**
+ * Meta keys for decorators
+ */
+/**
+ * Metadata key for Soft Deletes configuration.
+ * @internal
+ */
+export declare const SOFT_DELETES_KEY: unique symbol;
+/**
+ * Metadata key for Column definitions.
+ * @internal
+ */
+export declare const COLUMN_KEY: unique symbol;
+/**
+ * Metadata key for Version column.
+ * @internal
+ */
+export declare const VERSION_KEY: unique symbol;
+/**
+ * Soft Deletes Decorator
+ *
+ * Automatically adds a global scope to filter out deleted records.
+ * When applied to a Model class, it ensures that queries only return records
+ * where the deletion column (default 'deleted_at') is null.
+ *
+ * @param options - Configuration for soft deletes
+ *
+ * @example
+ * ```typescript
+ * @SoftDeletes({ column: 'deleted_at' })
+ * class User extends Model {
+ *   @column()
+ *   declare deletedAt: Date | null
+ * }
+ * ```
+ */
+export declare function SoftDeletes(options?: SoftDeletesOptions): ClassDecorator;
+/**
+ * Options for the Column decorator.
+ */
+export interface ColumnOptions {
+    /**
+     * Whether the column is a primary key.
+     * @default false
+     */
+    isPrimary?: boolean;
+    /**
+     * Whether the column should be automatically populated with a timestamp on creation.
+     * @default false
+     */
+    autoCreate?: boolean;
+    /**
+     * Whether the column should be automatically updated with a timestamp on every update.
+     * @default false
+     */
+    autoUpdate?: boolean;
+    /**
+     * The name of the column in the database.
+     * If not provided, the property name will be used.
+     */
+    name?: string;
+    /**
+     * The name to use when serializing the model to JSON.
+     * Set to null to hide the column from JSON output.
+     */
+    serializeAs?: string | null;
+}
+/**
+ * Column Decorator
+ *
+ * Marks a property as a database column. This decorator also triggers
+ * the registration of the model in the global ModelRegistry.
+ *
+ * @param options - Configuration for the column
+ *
+ * @example
+ * ```typescript
+ * class User extends Model {
+ *   @column({ isPrimary: true })
+ *   declare id: number
+ *
+ *   @column({ name: 'email_address' })
+ *   declare email: string
+ *
+ *   @column.dateTime({ autoCreate: true })
+ *   declare createdAt: Date
+ * }
+ * ```
+ */
+export declare function column(options?: ColumnOptions): PropertyDecorator;
+/**
+ * Version Decorator for Optimistic Locking
+ *
+ * Marks a property as a version column for optimistic locking.
+ * When a model updates, it checks if the version matches the one in the database.
+ *
+ * @param options - Configuration for the column (same as @column)
+ */
+export declare function version(options?: ColumnOptions): PropertyDecorator;

package/dist/atlas/src/orm/model/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Model Errors
+ * @description Custom error types for ORM model operations
+ */
+/**
+ * Column Not Found Error
+ * Thrown when accessing/setting a column that doesn't exist in schema
+ */
+export declare class ColumnNotFoundError extends Error {
+    readonly table: string;
+    readonly column: string;
+    constructor(table: string, column: string, availableColumns?: string[]);
+}
+/**
+ * Type Mismatch Error
+ * Thrown when setting a value with incompatible type
+ */
+export declare class TypeMismatchError extends Error {
+    readonly table: string;
+    readonly column: string;
+    readonly expectedType: string;
+    readonly actualType: string;
+    readonly value?: unknown | undefined;
+    constructor(table: string, column: string, expectedType: string, actualType: string, value?: unknown | undefined);
+}
+/**
+ * Nullable Constraint Error
+ * Thrown when setting null on a non-nullable column
+ */
+export declare class NullableConstraintError extends Error {
+    readonly table: string;
+    readonly column: string;
+    constructor(table: string, column: string);
+}
+/**
+ * Model Not Found Error
+ * Thrown when a model is not found in the database
+ */
+export declare class ModelNotFoundError extends Error {
+    readonly model: string;
+    readonly key: unknown;
+    constructor(model: string, key: unknown);
+}
+/**
+ * Stale Model Error
+ * Thrown when an optimistic lock check fails (concurrent update)
+ */
+export declare class StaleModelError extends Error {
+    readonly model: string;
+    readonly key: unknown;
+    constructor(model: string, key: unknown);
+}

package/dist/atlas/src/orm/model/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Model Module Index
+ */
+export { applyMixins, HasAttributes, HasEvents, HasPersistence, HasRelationships, HasSerialization, } from './concerns';
+export { DirtyTracker } from './DirtyTracker';
+export { column, SoftDeletes, version } from './decorators';
+export { ColumnNotFoundError, ModelNotFoundError, NullableConstraintError, TypeMismatchError, } from './errors';
+export { Model, type ModelAttributes, type ModelConstructor, type ModelStatic } from './Model';
+export { ModelRegistry } from './ModelRegistry';
+export { BelongsTo, BelongsToMany, eagerLoad, eagerLoadMany, getRelationships, HasMany, HasOne, MorphMany, MorphOne, MorphTo, type RelationshipMeta, type RelationshipOptions, type RelationType, } from './relationships';

package/dist/atlas/src/orm/model/relationships.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Relationship Types and Base Classes
+ * @description Declarative relationship definitions for ORM
+ */
+import type { QueryBuilderContract } from '../../types';
+import type { Model, ModelConstructor } from './Model';
+/**
+ * Relationship Type
+ */
+export type RelationType = 'hasOne' | 'hasMany' | 'belongsTo' | 'belongsToMany' | 'morphOne' | 'morphMany' | 'morphTo';
+/**
+ * Options for defining relationships between models.
+ */
+export interface RelationshipOptions {
+    /**
+     * The foreign key column name.
+     * - For `HasOne`/`HasMany`: Defaults to `parent_table_id` on the related table.
+     * - For `BelongsTo`: Defaults to `related_table_id` on the local table.
+     * - For `BelongsToMany`: Defaults to `parent_table_id` on the pivot table.
+     */
+    foreignKey?: string;
+    /**
+     * The local key column name.
+     * - For `HasOne`/`HasMany`: Defaults to the primary key of the local table.
+     * - For `BelongsTo`: Defaults to the primary key of the related table.
+     */
+    localKey?: string;
+    /**
+     * The name of the pivot table for many-to-many relationships.
+     * Defaults to an alphabetical concatenation of the two table names (e.g., `roles_users`).
+     */
+    pivotTable?: string;
+    /**
+     * The related key column name in the pivot table.
+     * Defaults to `related_table_id`.
+     */
+    relatedKey?: string;
+    /**
+     * Additional columns to select from the pivot table.
+     */
+    pivotColumns?: string[];
+}
+/**
+ * Relationship Metadata
+ */
+export interface RelationshipMeta {
+    type: RelationType;
+    related?: () => ModelConstructor<Model> & typeof Model;
+    foreignKey?: string;
+    localKey?: string;
+    pivotTable?: string | undefined;
+    relatedKey?: string | undefined;
+    pivotColumns?: string[] | undefined;
+    morphName?: string;
+    morphTypeField?: string;
+    morphIdField?: string;
+}
+/**
+ * Get relationships for a model
+ */
+export declare function getRelationships(model: typeof Model): Map<string, RelationshipMeta>;
+/**
+ * Define a relationship on a model
+ */
+export declare function defineRelationship(model: typeof Model, name: string, meta: RelationshipMeta): void;
+/**
+ * HasOne Relationship Decorator
+ *
+ * Defines a one-to-one relationship where the related model's table
+ * contains the foreign key.
+ *
+ * @param related - A factory function that returns the related Model class.
+ * @param options - Configuration for the relationship.
+ *
+ * @example
+ * ```typescript
+ * class User extends Model {
+ *   @HasOne(() => Profile)
+ *   declare profile: Profile
+ * }
+ * ```
+ */
+export declare function HasOne(related: () => ModelConstructor<Model> & typeof Model, options?: Omit<RelationshipOptions, 'pivotTable'>): PropertyDecorator;
+/**
+ * HasMany Relationship Decorator
+ *
+ * Defines a one-to-many relationship where the related model's table
+ * contains the foreign key.
+ *
+ * @param related - A factory function that returns the related Model class.
+ * @param options - Configuration for the relationship.
+ *
+ * @example
+ * ```typescript
+ * class User extends Model {
+ *   @HasMany(() => Post)
+ *   declare posts: Post[]
+ * }
+ * ```
+ */
+export declare function HasMany(related: () => ModelConstructor<Model> & typeof Model, options?: Omit<RelationshipOptions, 'pivotTable'>): PropertyDecorator;
+/**
+ * BelongsTo Relationship Decorator
+ *
+ * Defines an inverse relationship where the local model's table
+ * contains the foreign key.
+ *
+ * @param related - A factory function that returns the related Model class.
+ * @param options - Configuration for the relationship.
+ *
+ * @example
+ * ```typescript
+ * class Post extends Model {
+ *   @BelongsTo(() => User)
+ *   declare author: User
+ * }
+ * ```
+ */
+export declare function BelongsTo(related: () => ModelConstructor<Model> & typeof Model, options?: Omit<RelationshipOptions, 'pivotTable'>): PropertyDecorator;
+/**
+ * BelongsToMany Relationship Decorator
+ *
+ * Defines a many-to-many relationship using a pivot table.
+ *
+ * @param related - A factory function that returns the related Model class.
+ * @param options - Configuration for the relationship, including pivot table details.
+ *
+ * @example
+ * ```typescript
+ * class User extends Model {
+ *   @BelongsToMany(() => Role, { pivotTable: 'user_roles' })
+ *   declare roles: Role[]
+ * }
+ * ```
+ */
+export declare function BelongsToMany(related: () => ModelConstructor<Model> & typeof Model, options?: RelationshipOptions): PropertyDecorator;
+/**
+ * MorphOne Relationship Decorator
+ *
+ * Defines a polymorphic one-to-one relationship.
+ *
+ * @param related - A factory function that returns the related Model class.
+ * @param name - The name of the polymorphic relationship (e.g., 'imageable').
+ * @param options - Configuration for the relationship.
+ *
+ * @example
+ * ```typescript
+ * class Post extends Model {
+ *   @MorphOne(() => Image, 'imageable')
+ *   declare image: Image
+ * }
+ * ```
+ */
+export declare function MorphOne(related: () => ModelConstructor<Model> & typeof Model, name: string, options?: {
+    foreignKey?: string;
+    localKey?: string;
+}): PropertyDecorator;
+/**
+ * MorphMany Relationship Decorator
+ *
+ * Defines a polymorphic one-to-many relationship.
+ *
+ * @param related - A factory function that returns the related Model class.
+ * @param name - The name of the polymorphic relationship (e.g., 'commentable').
+ * @param options - Configuration for the relationship.
+ *
+ * @example
+ * ```typescript
+ * class Post extends Model {
+ *   @MorphMany(() => Comment, 'commentable')
+ *   declare comments: Comment[]
+ * }
+ * ```
+ */
+export declare function MorphMany(related: () => ModelConstructor<Model> & typeof Model, name: string, options?: {
+    foreignKey?: string;
+    localKey?: string;
+}): PropertyDecorator;
+/**
+ * MorphTo Relationship Decorator
+ *
+ * Defines the inverse of a polymorphic relationship.
+ *
+ * @param options - Configuration for the polymorphic relationship.
+ *
+ * @example
+ * ```typescript
+ * class Comment extends Model {
+ *   @MorphTo()
+ *   declare commentable: Post | Video
+ * }
+ * ```
+ */
+export declare function MorphTo(options?: {
+    name?: string;
+    typeField?: string;
+    idField?: string;
+}): PropertyDecorator;
+/**
+ * Load related models for a collection of parent models
+ * Uses batch queries to avoid N+1 problem
+ */
+export declare function eagerLoad<T extends Model, R extends Model = Model>(parents: T[], relationName: string, callback?: (query: QueryBuilderContract<R>) => void): Promise<void>;
+/**
+ * Load multiple relationships
+ */
+export declare function eagerLoadMany<T extends Model, R extends Model = Model>(parents: T[], relations: string[] | Record<string, unknown> | Map<string, (query: QueryBuilderContract<R>) => void>): Promise<void>;

package/dist/atlas/src/orm/model/types.d.ts

@@ -0,0 +1,12 @@
+import type { Model } from './Model';
+export interface ModelObserver<T extends Model> {
+    creating?(model: T): void | Promise<void>;
+    created?(model: T): void | Promise<void>;
+    updating?(model: T): void | Promise<void>;
+    updated?(model: T): void | Promise<void>;
+    deleting?(model: T): void | Promise<void>;
+    deleted?(model: T): void | Promise<void>;
+    saving?(model: T): void | Promise<void>;
+    saved?(model: T): void | Promise<void>;
+    retrieved?(model: T): void | Promise<void>;
+}