@guren/server 0.2.0-alpha.7 → 1.0.0-rc.9

package/dist/api-token-JOif2CtG.d.ts

@@ -0,0 +1,1792 @@
+import { MiddlewareHandler, Context } from 'hono';
+
+/** Accessor function: transforms a record field value after reading from DB. */
+type AccessorFn<T = unknown> = (record: PlainObject) => T;
+/** Mutator function: transforms a field value before writing to DB. */
+type MutatorFn<T = unknown> = (value: T, record: PlainObject) => unknown;
+/** Map of field names to accessor functions. */
+type AccessorDefinitions = Record<string, AccessorFn>;
+/** Map of field names to mutator functions. */
+type MutatorDefinitions = Record<string, MutatorFn>;
+
+type FieldKey<TRecord extends PlainObject> = keyof TRecord & string;
+/** Comparison operators supported by the QueryBuilder. */
+type WhereOperator = '=' | '!=' | '>' | '<' | '>=' | '<=' | 'like' | 'in' | 'not in' | 'is null' | 'is not null';
+/** A single field-level condition. */
+interface SimpleCondition {
+    type: 'simple';
+    field: string;
+    operator: WhereOperator;
+    value: unknown;
+}
+/** A group of conditions joined by AND or OR. */
+interface GroupCondition {
+    type: 'group';
+    boolean: 'and' | 'or';
+    conditions: WhereCondition[];
+}
+/** A where condition - either simple or grouped. */
+type WhereCondition = SimpleCondition | GroupCondition;
+/** Options carried by the QueryBuilder for query execution. */
+interface QueryBuilderOptions {
+    orderBy: Array<{
+        column: string;
+        direction: OrderDirection;
+    }>;
+    limitValue?: number;
+    offsetValue?: number;
+    selectFields?: readonly string[];
+    trx?: unknown;
+}
+/**
+ * Fluent query builder for the Guren ORM.
+ *
+ * Provides a chainable API for constructing database queries with
+ * support for complex where conditions, ordering, pagination, and more.
+ *
+ * Implements the thenable pattern so it can be directly awaited,
+ * resolving to the result of `get()`.
+ *
+ * @example
+ * // Fluent chaining
+ * const posts = await Post.where('status', 'published')
+ *   .where('views', '>', 100)
+ *   .orderBy('createdAt', 'desc')
+ *   .limit(10)
+ *   .get()
+ *
+ * // Thenable - await directly
+ * const active = await User.where('active', true)
+ *
+ * // Pagination
+ * const page = await Post.where('status', 'published').paginate(1, 20)
+ */
+declare class QueryBuilder<TRecord extends PlainObject = PlainObject, TResult extends PlainObject = TRecord> {
+    private conditions;
+    private options;
+    private modelClass;
+    private table;
+    private adapter;
+    private eagerLoad;
+    private eagerLoadConstraints;
+    constructor(modelClass: typeof Model, options?: {
+        trx?: unknown;
+    });
+    /**
+     * Add a where condition (AND).
+     *
+     * Supports three calling signatures:
+     * - `where(field, value)` - equality check
+     * - `where(field, operator, value)` - comparison
+     * - `where(object)` - multiple equality conditions
+     */
+    where<TKey extends FieldKey<TRecord>>(field: TKey, value: TRecord[TKey]): this;
+    where<TKey extends FieldKey<TRecord>>(field: TKey, operator: WhereOperator, value: unknown): this;
+    where(conditions: Partial<Record<FieldKey<TRecord>, unknown>>): this;
+    /**
+     * Add an OR where condition.
+     *
+     * Same overloads as `where()`, but joins with OR logic.
+     * Creates an OR group containing the new condition(s).
+     */
+    orWhere<TKey extends FieldKey<TRecord>>(field: TKey, value: TRecord[TKey]): this;
+    orWhere<TKey extends FieldKey<TRecord>>(field: TKey, operator: WhereOperator, value: unknown): this;
+    orWhere(conditions: Partial<Record<FieldKey<TRecord>, unknown>>): this;
+    /**
+     * Add a WHERE NULL condition.
+     * @param field - Column to check for NULL
+     */
+    whereNull(field: FieldKey<TRecord>): this;
+    /**
+     * Add a WHERE NOT NULL condition.
+     * @param field - Column to check for NOT NULL
+     */
+    whereNotNull(field: FieldKey<TRecord>): this;
+    /**
+     * Add a WHERE IN condition.
+     * @param field - Column to check
+     * @param values - Array of values to match against
+     */
+    whereIn<TKey extends FieldKey<TRecord>>(field: TKey, values: readonly TRecord[TKey][]): this;
+    /**
+     * Add a WHERE NOT IN condition.
+     * @param field - Column to check
+     * @param values - Array of values to exclude
+     */
+    whereNotIn<TKey extends FieldKey<TRecord>>(field: TKey, values: readonly TRecord[TKey][]): this;
+    /**
+     * Add an ORDER BY clause. Can be called multiple times to sort by multiple columns.
+     * @param field - Column to sort by
+     * @param direction - Sort direction (default: 'asc')
+     */
+    orderBy(field: FieldKey<TRecord>, direction?: OrderDirection): this;
+    /**
+     * Set the maximum number of records to return.
+     * @param n - Maximum record count
+     */
+    limit(n: number): this;
+    /**
+     * Set the number of records to skip.
+     * @param n - Number of records to skip
+     */
+    offset(n: number): this;
+    /**
+     * Limit the columns returned in the result.
+     * @param fields - Column names to select
+     */
+    select<TKey extends FieldKey<TRecord>>(...fields: readonly TKey[]): QueryBuilder<TRecord, Pick<TRecord, TKey>>;
+    /**
+     * Apply a named query scope defined on the model.
+     *
+     * @param name - The scope name
+     * @returns this (for chaining)
+     *
+     * @example
+     * const results = await Post.where('author', 'John')
+     *   .scope('published')
+     *   .scope('popular')
+     *   .get()
+     */
+    scope(name: string): this;
+    /**
+     * Eager-load relationships on query results.
+     *
+     * Supports string names, arrays, dot notation for nested relations,
+     * and constraint callbacks.
+     *
+     * @example
+     * // Simple
+     * await User.where('active', true).with('posts').get()
+     *
+     * // Multiple
+     * await User.where('active', true).with('posts', 'comments').get()
+     *
+     * // Nested (dot notation)
+     * await User.where('active', true).with('posts.comments').get()
+     */
+    with(...relations: (string | Record<string, (q: QueryBuilder<any>) => void>)[]): this;
+    /**
+     * Execute the query and return all matching records.
+     * @returns Array of matching records
+     */
+    get(): Promise<TResult[]>;
+    /**
+     * Execute the query and return the first matching record.
+     * @returns The first record or null
+     */
+    first(): Promise<TResult | null>;
+    /**
+     * Execute the query and return the first matching record, or throw.
+     * @returns The first record
+     * @throws Error if no record matches
+     */
+    firstOrFail(): Promise<TResult>;
+    /**
+     * Count the number of records matching the current conditions.
+     * @returns The count of matching records
+     */
+    count(): Promise<number>;
+    /**
+     * Paginate the query results.
+     * @param page - Page number (1-based, default: 1)
+     * @param perPage - Records per page (default: 15)
+     * @returns Paginated result with data and metadata
+     */
+    paginate(page?: number, perPage?: number): Promise<PaginatedResult<TResult>>;
+    /**
+     * Bulk update records matching the current conditions.
+     * @param data - Data to set on matching records
+     * @returns The updated record (adapter-dependent)
+     */
+    update(data: PlainObject): Promise<TRecord>;
+    /**
+     * Bulk delete records matching the current conditions.
+     * @returns Number of deleted records (adapter-dependent)
+     */
+    delete(): Promise<number | PlainObject | void>;
+    /**
+     * Makes QueryBuilder a thenable so it can be directly awaited.
+     * Resolves to the result of `get()`.
+     */
+    then<TResult1 = TResult[], TResult2 = never>(onfulfilled?: ((value: TResult[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    /**
+     * Catch handler for the thenable interface.
+     */
+    catch<TCatch = never>(onrejected?: ((reason: unknown) => TCatch | PromiseLike<TCatch>) | null): Promise<TResult[] | TCatch>;
+    /** Get the internal conditions (used by adapters). */
+    getConditions(): WhereCondition[];
+    /** Get the internal query options (used by adapters). */
+    getOptions(): QueryBuilderOptions;
+    private addSimpleCondition;
+    private executeQuery;
+    /**
+     * Attempt to convert the current conditions to a simple WhereClause
+     * for backward compatibility with basic adapters.
+     * Returns null if conditions are too complex.
+     */
+    private toSimpleWhereClause;
+    /**
+     * Load eager relations onto fetched results.
+     * Supports dot notation for nested relations (e.g., 'posts.comments').
+     */
+    private readonly loadEagerRelations;
+}
+
+/** A named global scope function. */
+type ScopeFunction = (q: QueryBuilder<any>) => QueryBuilder<any>;
+/**
+ * Registry for named global scopes on a model.
+ *
+ * Supports adding, removing, and applying multiple named scopes.
+ * Used internally by Model to manage global query constraints.
+ */
+declare class GlobalScopeRegistry {
+    private scopes;
+    add(name: string, fn: ScopeFunction): void;
+    remove(name: string): void;
+    has(name: string): boolean;
+    names(): string[];
+    /** Apply all scopes (or all except excluded) to a query builder. */
+    apply<T extends PlainObject>(builder: QueryBuilder<T>, except?: string[]): QueryBuilder<T>;
+    clear(): void;
+    get size(): number;
+}
+
+/**
+ * Model lifecycle hook names.
+ *
+ * "Before" hooks (`creating`, `updating`, `deleting`, `saving`) fire before
+ * the database operation. If they return `false`, the operation is aborted.
+ *
+ * "After" hooks (`created`, `updated`, `deleted`, `saved`) fire after the
+ * database operation completes.
+ *
+ * `saving`/`saved` fire for both create and update operations.
+ */
+type HookName = 'creating' | 'created' | 'updating' | 'updated' | 'deleting' | 'deleted' | 'saving' | 'saved';
+/**
+ * Callback signature for model lifecycle hooks.
+ *
+ * @param data - The record data being operated on
+ * @returns void for after-hooks. Returning `false` from a before-hook aborts the operation.
+ */
+type HookCallback<T = Record<string, unknown>> = (data: T) => void | Promise<void> | false | Promise<false>;
+/**
+ * Map of hook names to their callbacks.
+ * All hooks are optional.
+ */
+type ModelHooks = {
+    [K in HookName]?: HookCallback;
+};
+
+/**
+ * Base interface for model observers.
+ *
+ * Observers allow extracting lifecycle hook logic into dedicated classes.
+ * Each method corresponds to a model lifecycle event and is optional.
+ *
+ * @example
+ * class UserObserver implements ModelObserver {
+ *   async creating(data) { data.slug = slugify(data.name) }
+ *   async created(data) { await sendWelcomeEmail(data) }
+ * }
+ *
+ * User.observe(UserObserver)
+ */
+interface ModelObserver {
+    creating?(data: PlainObject): void | Promise<void> | false | Promise<false>;
+    created?(data: PlainObject): void | Promise<void>;
+    updating?(data: PlainObject): void | Promise<void> | false | Promise<false>;
+    updated?(data: PlainObject): void | Promise<void>;
+    deleting?(data: PlainObject): void | Promise<void> | false | Promise<false>;
+    deleted?(data: PlainObject): void | Promise<void>;
+    saving?(data: PlainObject): void | Promise<void> | false | Promise<false>;
+    saved?(data: PlainObject): void | Promise<void>;
+}
+type ModelObserverConstructor = new () => ModelObserver;
+
+/** Generic plain object type used throughout the ORM. */
+type PlainObject = Record<string, unknown>;
+type RelationShape = Record<string, unknown>;
+/** Supported cast types for attribute casting. */
+type CastType = 'json' | 'date' | 'boolean' | 'number' | 'string';
+/**
+ * Value type for where clause conditions.
+ * Supports single values, arrays (for IN queries), or null.
+ */
+type WhereValue<Value> = Value | readonly Value[] | null;
+/**
+ * Where clause for filtering records.
+ * Supports equality and IN (array) queries.
+ *
+ * @example
+ * // Single value (equality)
+ * { status: 'active' }
+ *
+ * // Array value (IN query)
+ * { id: [1, 2, 3] }
+ *
+ * // Multiple conditions (AND)
+ * { status: 'active', role: 'admin' }
+ */
+type WhereClause<TRecord extends PlainObject = PlainObject> = Partial<{
+    [K in keyof TRecord & string]?: WhereValue<TRecord[K]>;
+}>;
+/** Sort direction for ordering queries. */
+type OrderDirection = 'asc' | 'desc';
+/** Normalized order definition with column and direction. */
+type OrderDefinition<TRecord extends PlainObject = PlainObject> = {
+    column: keyof TRecord & string;
+    direction: OrderDirection;
+};
+/**
+ * Flexible order expression input.
+ * @example
+ * 'createdAt'                        // Column name (ascending)
+ * ['createdAt', 'desc']              // Tuple [column, direction]
+ * { column: 'createdAt', direction: 'desc' }  // Object form
+ */
+type OrderExpression<TRecord extends PlainObject = PlainObject> = (keyof TRecord & string) | readonly [keyof TRecord & string, OrderDirection] | {
+    column: keyof TRecord & string;
+    direction?: OrderDirection;
+};
+/** Input for orderBy - single expression or array of expressions. */
+type OrderByInput<TRecord extends PlainObject = PlainObject> = OrderExpression<TRecord> | readonly OrderExpression<TRecord>[];
+/** Normalized array of order definitions. */
+type OrderByClause<TRecord extends PlainObject = PlainObject> = readonly OrderDefinition<TRecord>[];
+/** Options for findMany queries. */
+interface FindManyOptions<TRecord extends PlainObject = PlainObject> {
+    /** Filter conditions */
+    where?: WhereClause<TRecord>;
+    /** Sort order */
+    orderBy?: OrderByClause<TRecord>;
+    /** Maximum number of records to return */
+    limit?: number;
+    /** Number of records to skip */
+    offset?: number;
+}
+/** Options for paginated queries. */
+interface PaginateOptions<TRecord extends PlainObject = PlainObject> {
+    /** Page number (1-based, default: 1) */
+    page?: number;
+    /** Records per page (default: 15) */
+    perPage?: number;
+    /** Filter conditions */
+    where?: WhereClause<TRecord>;
+    /** Sort order */
+    orderBy?: OrderByInput<TRecord>;
+}
+/** Pagination metadata returned with paginated results. */
+interface PaginationMeta {
+    /** Total number of records matching the query */
+    total: number;
+    /** Number of records per page */
+    perPage: number;
+    /** Current page number (1-based) */
+    currentPage: number;
+    /** Total number of pages */
+    totalPages: number;
+    /** Whether there are more pages after this one */
+    hasMore: boolean;
+    /** Index of first record on this page (1-based) */
+    from: number;
+    /** Index of last record on this page */
+    to: number;
+}
+/** Result of a paginated query. */
+interface PaginatedResult<TRecord extends PlainObject = PlainObject> {
+    /** Records for the current page */
+    data: TRecord[];
+    /** Pagination metadata */
+    meta: PaginationMeta;
+}
+/**
+ * Interface for ORM adapters that power the Model class.
+ * The default adapter is DrizzleAdapter.
+ */
+interface ORMAdapter {
+    /** Run operations in a database transaction. */
+    transaction?<TResult>(callback: (trx: unknown) => Promise<TResult>): Promise<TResult>;
+    /** Find multiple records with optional filtering, ordering, and pagination. */
+    findMany<TRecord extends PlainObject = PlainObject>(table: unknown, options?: FindManyOptions<TRecord>, queryOptions?: AdapterQueryOptions): Promise<TRecord[]>;
+    /** Find a single record by unique criteria. */
+    findUnique<TRecord extends PlainObject = PlainObject>(table: unknown, where: WhereClause<TRecord>, queryOptions?: AdapterQueryOptions): Promise<TRecord | null>;
+    /** Create a new record. */
+    create<TRecord extends PlainObject = PlainObject>(table: unknown, data: PlainObject, writeOptions?: AdapterQueryOptions): Promise<TRecord>;
+    /** Update records matching criteria. */
+    update?<TRecord extends PlainObject = PlainObject>(table: unknown, where: WhereClause<TRecord>, data: PlainObject, writeOptions?: AdapterQueryOptions): Promise<TRecord>;
+    /** Delete records matching criteria. */
+    delete?<TRecord extends PlainObject = PlainObject>(table: unknown, where: WhereClause<TRecord>, writeOptions?: AdapterQueryOptions): Promise<number | PlainObject | void>;
+    /** Count records matching criteria. */
+    count?<TRecord extends PlainObject = PlainObject>(table: unknown, where?: WhereClause<TRecord>, queryOptions?: AdapterQueryOptions): Promise<number>;
+}
+interface AdapterQueryOptions {
+    trx?: unknown;
+}
+type ModelWriteOptions = AdapterQueryOptions;
+type ModelQueryOptions = AdapterQueryOptions;
+type TransactionHandle = NonNullable<AdapterQueryOptions['trx']>;
+type SelectFrom<TDatabase> = TDatabase extends {
+    select: (...args: any[]) => infer TSelect;
+} ? TSelect extends {
+    from: (...args: any[]) => infer TResult;
+} ? TResult : never : never;
+/**
+ * ActiveRecord-style base class for database models.
+ *
+ * Provides a Laravel Eloquent-like API for database operations including
+ * CRUD, querying, pagination, and eager-loading of relationships.
+ *
+ * @example
+ * // Define a model
+ * class User extends Model<UserRecord> {
+ *   static override table = users  // Drizzle table
+ *   static override readonly recordType = {} as UserRecord
+ * }
+ *
+ * // Query records
+ * const allUsers = await User.all()
+ * const user = await User.find(1)
+ * const activeUsers = await User.where({ status: 'active' })
+ *
+ * // Create and update
+ * const newUser = await User.create({ name: 'John', email: 'john@example.com' })
+ * await User.update({ id: 1 }, { name: 'Jane' })
+ *
+ * // Pagination
+ * const page = await User.paginate({ page: 1, perPage: 10 })
+ *
+ * // Relationships
+ * const usersWithPosts = await User.with('posts')
+ */
+declare abstract class Model<TRecord extends PlainObject = PlainObject> {
+    /** The ORM adapter used for database operations. */
+    protected static ormAdapter: ORMAdapter;
+    /** The database table (e.g., Drizzle table schema). */
+    protected static table: unknown;
+    /** Type marker for TypeScript inference. Define as `{} as YourRecordType`. */
+    static readonly recordType: unknown;
+    /** Type marker for insert/update payload inference. Define as `{} as typeof table.$inferInsert`. */
+    static readonly createType: unknown;
+    protected static relationDefinitions?: Map<string, RelationDefinition>;
+    /** Type marker for relation types. Define relation types here for type inference. */
+    static relationTypes: RelationShape;
+    /**
+     * Named query scopes for reusable query constraints.
+     *
+     * @example
+     * class Post extends Model<PostRecord> {
+     *   static scopes = {
+     *     published: (q: QueryBuilder<PostRecord>) => q.where('status', 'published'),
+     *     popular: (q: QueryBuilder<PostRecord>) => q.where('views', '>', 1000),
+     *   }
+     * }
+     * // Usage: Post.scope('published').scope('popular').get()
+     */
+    static scopes?: Record<string, (q: QueryBuilder<any>) => QueryBuilder<any>>;
+    /**
+     * Default scope applied to all queries on this model.
+     * Override this to automatically filter queries (e.g., soft deletes).
+     *
+     * @example
+     * static defaultScope = (q: QueryBuilder<any>) => q.whereNull('deletedAt')
+     */
+    static defaultScope?: (q: QueryBuilder<any>) => QueryBuilder<any>;
+    /**
+     * Model lifecycle hooks that fire during create, update, and delete operations.
+     *
+     * @example
+     * class User extends Model<UserRecord> {
+     *   static hooks: ModelHooks = {
+     *     creating: async (data) => { data.password = await hash(data.password as string) },
+     *     created: async (data) => { console.log('User created:', data) },
+     *   }
+     * }
+     */
+    static hooks?: ModelHooks;
+    /**
+     * Attribute casting definitions for automatic type conversion.
+     *
+     * Casts are applied when reading records from the database and when
+     * writing records to the database.
+     *
+     * @example
+     * class Post extends Model<PostRecord> {
+     *   static casts = {
+     *     metadata: 'json',
+     *     publishedAt: 'date',
+     *     isActive: 'boolean',
+     *     viewCount: 'number',
+     *   }
+     * }
+     */
+    static casts?: Record<string, CastType>;
+    /**
+     * Whitelist of fields allowed for mass assignment.
+     * If set, only these fields will be accepted in `create()` and `update()`.
+     *
+     * @example
+     * class User extends Model<UserRecord> {
+     *   static fillable = ['name', 'email', 'password']
+     * }
+     */
+    static fillable?: string[];
+    /**
+     * Blacklist of fields excluded from mass assignment.
+     * Defaults to `['id']`. Ignored if `fillable` is set.
+     *
+     * @example
+     * class Post extends Model<PostRecord> {
+     *   static guarded = ['id', 'createdAt']
+     * }
+     */
+    static guarded?: string[];
+    /**
+     * Accessor functions for computed/virtual attributes.
+     * Applied after reading records from the database.
+     *
+     * @example
+     * class User extends Model<UserRecord> {
+     *   static accessors = {
+     *     fullName: (record) => `${record.firstName} ${record.lastName}`,
+     *   }
+     * }
+     */
+    static accessors?: AccessorDefinitions;
+    /**
+     * Mutator functions for transforming attributes before persistence.
+     *
+     * @example
+     * class User extends Model<UserRecord> {
+     *   static mutators = {
+     *     email: (value) => String(value).toLowerCase(),
+     *   }
+     * }
+     */
+    static mutators?: MutatorDefinitions;
+    /**
+     * Fields to exclude from serialization output.
+     *
+     * @example
+     * class User extends Model<UserRecord> {
+     *   static hidden = ['passwordHash', 'rememberToken']
+     * }
+     */
+    static hidden?: string[];
+    /**
+     * Whitelist of fields to include in serialization output.
+     * When set, only these fields appear. Takes precedence over `hidden`.
+     */
+    static visible?: string[];
+    /**
+     * Virtual accessor attributes to include in serialization output.
+     *
+     * @example
+     * class User extends Model<UserRecord> {
+     *   static appends = ['fullName']
+     *   static accessors = { fullName: (r) => `${r.firstName} ${r.lastName}` }
+     * }
+     */
+    static appends?: string[];
+    /** Registered model observers. */
+    protected static observers?: ModelObserver[];
+    /** Named global scopes registry. */
+    protected static globalScopeRegistry?: GlobalScopeRegistry;
+    /**
+     * Set a custom ORM adapter for this model.
+     * @param adapter - The adapter to use
+     */
+    static useAdapter(adapter: ORMAdapter): void;
+    /**
+     * Get the current ORM adapter.
+     * @returns The configured adapter
+     */
+    static getAdapter(): ORMAdapter;
+    /**
+     * Run operations inside a database transaction.
+     *
+     * @example
+     * await User.transaction(async (trx) => {
+     *   const user = await User.create({ name: 'John' }, { trx })
+     *   await Profile.create({ userId: user.id }, { trx })
+     * })
+     */
+    static transaction<T extends typeof Model, TResult>(this: T, callback: (trx: TransactionHandle, scope: TransactionModelScope<T>) => Promise<TResult>): Promise<TResult>;
+    /**
+     * Create a transaction-bound model scope that automatically forwards `trx`
+     * to query and write operations.
+     *
+     * @example
+     * await User.transaction(async (trx, txUser) => {
+     *   await txUser.create({ name: 'Shinji' })
+     *   await txUser.update({ id: 1 }, { name: 'Ikari' })
+     * })
+     */
+    static inTransaction<T extends typeof Model>(this: T, trx: TransactionHandle): TransactionModelScope<T>;
+    /**
+     * Register a model observer class.
+     *
+     * @example
+     * User.observe(UserObserver)
+     */
+    static observe(ObserverClass: ModelObserverConstructor): void;
+    /** Clear all registered observers. */
+    static clearObservers(): void;
+    protected static getGlobalScopes(): GlobalScopeRegistry;
+    /**
+     * Register a named global scope.
+     *
+     * @example
+     * User.addGlobalScope('active', (q) => q.where('active', true))
+     */
+    static addGlobalScope(name: string, fn: ScopeFunction): void;
+    /** Remove a named global scope. */
+    static removeGlobalScope(name: string): void;
+    /**
+     * Start a query excluding specific global scope(s).
+     *
+     * @example
+     * const all = await User.withoutGlobalScope('active').get()
+     */
+    static withoutGlobalScope<T extends typeof Model>(this: T, ...names: string[]): QueryBuilder<TRecordFor<T>>;
+    /**
+     * Start a query with no global scopes applied (also skips defaultScope).
+     *
+     * @example
+     * const all = await User.withoutGlobalScopes().get()
+     */
+    static withoutGlobalScopes<T extends typeof Model>(this: T): QueryBuilder<TRecordFor<T>>;
+    /**
+     * Serialize a record for API/JSON output.
+     * Applies hidden/visible filtering, accessors, and appends.
+     *
+     * @example
+     * const json = User.serialize(user)
+     */
+    static serialize<T extends typeof Model>(this: T, record: TRecordFor<T>): PlainObject;
+    /**
+     * Serialize an array of records.
+     *
+     * @example
+     * const json = User.serializeMany(users)
+     */
+    static serializeMany<T extends typeof Model>(this: T, records: TRecordFor<T>[]): PlainObject[];
+    /**
+     * Apply attribute casts to a record read from the database.
+     *
+     * @param record - The raw record from the database
+     * @returns The record with cast attributes applied
+     */
+    static applyCasts<T extends PlainObject>(record: T): T;
+    /**
+     * Apply all read-time transforms: casts then accessors.
+     * Used internally after fetching records from the database.
+     */
+    protected static applyReadTransforms<T extends PlainObject>(record: T): T;
+    /**
+     * Filter input data based on mass assignment protection rules.
+     *
+     * If `fillable` is defined, only fields listed in `fillable` are kept.
+     * Otherwise, fields listed in `guarded` (default: `['id']`) are removed.
+     *
+     * @param data - The input data to filter
+     * @returns Filtered data safe for mass assignment
+     */
+    static filterFillable(data: PlainObject): PlainObject;
+    protected static preparePersistencePayload(data: PlainObject): Promise<PlainObject>;
+    protected static getRelationDefinitions(): Map<string, RelationDefinition>;
+    /** @internal */
+    static getRelationDefinition(name: string): RelationDefinition | undefined;
+    static resolveTable(): unknown;
+    /**
+     * Retrieve all records from the table.
+     *
+     * @returns Array of all records
+     *
+     * @example
+     * const users = await User.all()
+     */
+    static all<T extends typeof Model>(this: T, queryOptions?: ModelQueryOptions): Promise<Array<TRecordFor<T>>>;
+    /**
+     * Find a record by its primary key.
+     *
+     * @param id - The primary key value
+     * @param key - The primary key column name (default: 'id')
+     * @returns The record or null if not found
+     *
+     * @example
+     * const user = await User.find(1)
+     * const userByEmail = await User.find('john@example.com', 'email')
+     */
+    static find<T extends typeof Model>(this: T, id: TRecordFor<T>[keyof TRecordFor<T> & string], key?: keyof TRecordFor<T> & string, queryOptions?: ModelQueryOptions): Promise<TRecordFor<T> | null>;
+    /**
+     * Find a record by primary key or throw an error.
+     *
+     * @param id - The primary key value
+     * @param key - The primary key column name (default: 'id')
+     * @returns The record
+     * @throws Error if record not found
+     *
+     * @example
+     * const user = await User.findOrFail(1) // Throws if not found
+     */
+    static findOrFail<T extends typeof Model>(this: T, id: TRecordFor<T>[keyof TRecordFor<T> & string], key?: keyof TRecordFor<T> & string, queryOptions?: ModelQueryOptions): Promise<TRecordFor<T>>;
+    /**
+     * Find a record by primary key with eager-loaded relations.
+     *
+     * @param id - The primary key value
+     * @param relations - Relation name(s) to eager load
+     * @param key - The primary key column name (default: 'id')
+     * @returns The record with loaded relations, or null if not found
+     *
+     * @example
+     * const post = await Post.findWith(1, 'author')
+     * const post = await Post.findWith(1, ['author', 'tags'])
+     */
+    static findWith<T extends typeof Model, K extends RelationKey<T>>(this: T, id: TRecordFor<T>[keyof TRecordFor<T> & string], relations: K | readonly K[], key?: keyof TRecordFor<T> & string): Promise<(TRecordFor<T> & RelationTypePick<T, K | readonly K[]>) | null>;
+    /**
+     * Find a record by primary key with eager-loaded relations, or throw.
+     *
+     * @param id - The primary key value
+     * @param relations - Relation name(s) to eager load
+     * @param key - The primary key column name (default: 'id')
+     * @returns The record with loaded relations
+     * @throws ModelNotFoundException if record not found
+     *
+     * @example
+     * const post = await Post.findWithOrFail(1, 'author')
+     * const post = await Post.findWithOrFail(1, ['author', 'tags'])
+     */
+    static findWithOrFail<T extends typeof Model, K extends RelationKey<T>>(this: T, id: TRecordFor<T>[keyof TRecordFor<T> & string], relations: K | readonly K[], key?: keyof TRecordFor<T> & string): Promise<TRecordFor<T> & RelationTypePick<T, K | readonly K[]>>;
+    /**
+     * Get the first record matching the conditions.
+     *
+     * @param where - Optional filter conditions
+     * @returns The first matching record or null
+     *
+     * @example
+     * const admin = await User.first({ role: 'admin' })
+     */
+    static first<T extends typeof Model>(this: T, where?: WhereClauseFor<T>, queryOptions?: ModelQueryOptions): Promise<TRecordFor<T> | null>;
+    /**
+     * Start a fluent query with where conditions.
+     *
+     * Returns a QueryBuilder that is thenable, so it can be directly awaited.
+     *
+     * @example
+     * // Object form - multiple equality conditions
+     * const activeUsers = await User.where({ status: 'active' })
+     *
+     * // Field + value - equality
+     * const admins = await User.where('role', 'admin')
+     *
+     * // Field + operator + value - comparison
+     * const recent = await Post.where('views', '>', 100)
+     *
+     * // Fluent chaining
+     * const posts = await Post.where('status', 'published')
+     *   .where('views', '>', 100)
+     *   .orderBy('createdAt', 'desc')
+     *   .limit(10)
+     *   .get()
+     */
+    static where<T extends typeof Model>(this: T, conditions: WhereClauseFor<T>): QueryBuilder<TRecordFor<T>>;
+    static where<T extends typeof Model>(this: T, field: keyof TRecordFor<T> & string, value: unknown): QueryBuilder<TRecordFor<T>>;
+    static where<T extends typeof Model>(this: T, field: keyof TRecordFor<T> & string, operator: WhereOperator, value: unknown): QueryBuilder<TRecordFor<T>>;
+    /**
+     * Start a fluent query with a WHERE NULL condition.
+     * @param field - Column to check for NULL
+     */
+    static whereNull<T extends typeof Model>(this: T, field: keyof TRecordFor<T> & string): QueryBuilder<TRecordFor<T>>;
+    /**
+     * Start a fluent query with a WHERE NOT NULL condition.
+     * @param field - Column to check for NOT NULL
+     */
+    static whereNotNull<T extends typeof Model>(this: T, field: keyof TRecordFor<T> & string): QueryBuilder<TRecordFor<T>>;
+    /**
+     * Start a fluent query with a WHERE IN condition.
+     * @param field - Column to check
+     * @param values - Array of values to match against
+     */
+    static whereIn<T extends typeof Model>(this: T, field: keyof TRecordFor<T> & string, values: readonly TRecordFor<T>[keyof TRecordFor<T> & string][]): QueryBuilder<TRecordFor<T>>;
+    /**
+     * Start a fluent query with a WHERE NOT IN condition.
+     * @param field - Column to check
+     * @param values - Array of values to exclude
+     */
+    static whereNotIn<T extends typeof Model>(this: T, field: keyof TRecordFor<T> & string, values: readonly TRecordFor<T>[keyof TRecordFor<T> & string][]): QueryBuilder<TRecordFor<T>>;
+    /**
+     * Start a fluent query with a typed field selection.
+     *
+     * @example
+     * const rows = await User.select('id', 'name')
+     * const first = await User.select('id').first()
+     */
+    static select<T extends typeof Model, Keys extends keyof TRecordFor<T> & string>(this: T, ...fields: readonly Keys[]): QueryBuilder<TRecordFor<T>, Pick<TRecordFor<T>, Keys>>;
+    /**
+     * Start a new QueryBuilder for fluent query construction.
+     *
+     * @returns A fresh QueryBuilder instance
+     *
+     * @example
+     * const results = await User.newQuery()
+     *   .where('status', 'active')
+     *   .orderBy('name')
+     *   .limit(10)
+     *   .get()
+     */
+    static newQuery<T extends typeof Model>(this: T, queryOptions?: ModelQueryOptions): QueryBuilder<TRecordFor<T>>;
+    /**
+     * Create a new QueryBuilder without applying any default scopes.
+     * Useful for querying soft-deleted records or bypassing global filters.
+     *
+     * @returns A fresh QueryBuilder instance with no scopes applied
+     */
+    static newQueryWithoutScopes<T extends typeof Model>(this: T, queryOptions?: ModelQueryOptions): QueryBuilder<TRecordFor<T>>;
+    /**
+     * Apply a named query scope.
+     *
+     * @param name - The scope name defined in `static scopes`
+     * @returns A QueryBuilder with the scope applied
+     *
+     * @example
+     * const published = await Post.scope('published').get()
+     * const popularPublished = await Post.scope('published').scope('popular').get()
+     */
+    static scope<T extends typeof Model>(this: T, name: string): QueryBuilder<TRecordFor<T>>;
+    /**
+     * Define a one-to-many relationship.
+     *
+     * @param name - Relation name (used in `with()` calls)
+     * @param related - The related model class
+     * @param foreignKey - Foreign key column on the related model
+     * @param localKey - Local key column on this model
+     *
+     * @example
+     * class User extends Model<UserRecord> {
+     *   static {
+     *     this.hasMany('posts', Post, 'userId', 'id')
+     *   }
+     * }
+     * // Later: User.with('posts')
+     */
+    static hasMany<This extends typeof Model, Related extends typeof Model, ForeignKey extends keyof TRecordFor<Related> & string, LocalKey extends keyof TRecordFor<This> & string, Name extends RelationKeyOrString<This>>(this: This, name: Name, related: Related | (() => Related | Promise<Related>), foreignKey: ForeignKey, localKey: LocalKey): void;
+    /**
+     * Define a many-to-one (inverse) relationship.
+     *
+     * @param name - Relation name (used in `with()` calls)
+     * @param related - The related model class
+     * @param foreignKey - Foreign key column on this model
+     * @param ownerKey - Primary key column on the related model
+     *
+     * @example
+     * class Post extends Model<PostRecord> {
+     *   static {
+     *     this.belongsTo('author', User, 'userId', 'id')
+     *   }
+     * }
+     * // Later: Post.with('author')
+     */
+    static belongsTo<This extends typeof Model, Related extends typeof Model, ForeignKey extends keyof TRecordFor<This> & string, OwnerKey extends keyof TRecordFor<Related> & string, Name extends RelationKeyOrString<This>>(this: This, name: Name, related: Related | (() => Related | Promise<Related>), foreignKey: ForeignKey, ownerKey: OwnerKey): void;
+    /**
+     * Define a one-to-one relationship.
+     *
+     * @param name - Relation name (used in `with()` calls)
+     * @param related - The related model class
+     * @param foreignKey - Foreign key column on the related model
+     * @param localKey - Local key column on this model
+     *
+     * @example
+     * class User extends Model<UserRecord> {
+     *   static {
+     *     this.hasOne('profile', Profile, 'userId', 'id')
+     *   }
+     * }
+     * // Later: User.with('profile')
+     */
+    static hasOne<This extends typeof Model, Related extends typeof Model, ForeignKey extends keyof TRecordFor<Related> & string, LocalKey extends keyof TRecordFor<This> & string, Name extends RelationKeyOrString<This>>(this: This, name: Name, related: Related | (() => Related | Promise<Related>), foreignKey: ForeignKey, localKey: LocalKey): void;
+    /**
+     * Define a many-to-many relationship via a pivot table.
+     *
+     * @param name - Relation name (used in `with()` calls)
+     * @param related - The related model class
+     * @param pivotTable - The pivot/junction table (e.g., Drizzle table schema)
+     * @param foreignPivotKey - Column on pivot table referencing this model
+     * @param relatedPivotKey - Column on pivot table referencing the related model
+     * @param parentKey - Local key on this model (default: 'id')
+     * @param relatedKey - Local key on the related model (default: 'id')
+     *
+     * @example
+     * class User extends Model<UserRecord> {
+     *   static {
+     *     this.belongsToMany('roles', Role, userRoles, 'userId', 'roleId', 'id', 'id')
+     *   }
+     * }
+     * // Later: User.with('roles')
+     */
+    static belongsToMany<This extends typeof Model, Related extends typeof Model, Name extends RelationKeyOrString<This>>(this: This, name: Name, related: Related | (() => Related | Promise<Related>), pivotTable: unknown, foreignPivotKey: string, relatedPivotKey: string, parentKey?: string, relatedKey?: string): void;
+    /**
+     * Define a has-many-through relationship.
+     *
+     * @param name - Relation name (used in `with()` calls)
+     * @param related - The final related model class
+     * @param through - The intermediate model class
+     * @param firstKey - Foreign key on the intermediate model referencing this model
+     * @param secondKey - Foreign key on the related model referencing the intermediate model
+     * @param localKey - Local key on this model (default: 'id')
+     * @param secondLocalKey - Local key on the intermediate model (default: 'id')
+     *
+     * @example
+     * class Country extends Model<CountryRecord> {
+     *   static {
+     *     this.hasManyThrough('posts', Post, User, 'countryId', 'userId', 'id', 'id')
+     *   }
+     * }
+     * // Later: Country.with('posts')
+     */
+    static hasManyThrough<This extends typeof Model, Related extends typeof Model, Through extends typeof Model, Name extends RelationKeyOrString<This>>(this: This, name: Name, related: Related | (() => Related | Promise<Related>), through: Through | (() => Through | Promise<Through>), firstKey: string, secondKey: string, localKey?: string, secondLocalKey?: string): void;
+    /**
+     * Map of type strings to model classes for polymorphic relationships.
+     *
+     * @example
+     * Model.morphMap = { Post, Video }
+     */
+    static morphMap?: Record<string, typeof Model>;
+    /**
+     * Define a one-to-many polymorphic relationship.
+     *
+     * @param name - Relation name
+     * @param related - The related model class
+     * @param morphName - Base name for the type/id columns (e.g. 'commentable' → commentableType + commentableId)
+     * @param localKey - Local key on this model (default: 'id')
+     *
+     * @example
+     * Post.morphMany('comments', Comment, 'commentable', 'id')
+     */
+    static morphMany<This extends typeof Model, Related extends typeof Model, Name extends RelationKeyOrString<This>>(this: This, name: Name, related: Related | (() => Related | Promise<Related>), morphName: string, localKey?: string): void;
+    /**
+     * Define the inverse of a polymorphic relationship.
+     *
+     * @param name - Relation name
+     * @param morphName - Base name for the type/id columns
+     *
+     * @example
+     * Comment.morphTo('commentable', 'commentable')
+     */
+    static morphTo<This extends typeof Model, Name extends RelationKeyOrString<This>>(this: This, name: Name, morphName: string): void;
+    /**
+     * Get records sorted by the specified order.
+     *
+     * @param order - Order expression(s)
+     * @param where - Optional filter conditions
+     * @returns Sorted array of records
+     *
+     * @example
+     * // Single column ascending
+     * await User.orderBy('createdAt')
+     *
+     * // Single column descending
+     * await User.orderBy(['createdAt', 'desc'])
+     *
+     * // Multiple columns
+     * await User.orderBy([['lastName', 'asc'], ['firstName', 'asc']])
+     *
+     * // With where clause
+     * await User.orderBy('name', { status: 'active' })
+     */
+    static orderBy<T extends typeof Model>(this: T, order: OrderByInput<TRecordFor<T>>, where?: WhereClauseFor<T>, queryOptions?: ModelQueryOptions): Promise<TRecordFor<T>[]>;
+    /**
+     * Get paginated records.
+     *
+     * @param options - Pagination options
+     * @returns Paginated result with data and metadata
+     *
+     * @example
+     * const result = await User.paginate({ page: 1, perPage: 10 })
+     * // result.data - Array of users
+     * // result.meta.total - Total count
+     * // result.meta.hasMore - Whether there are more pages
+     *
+     * // With filtering and ordering
+     * await User.paginate({
+     *   page: 2,
+     *   perPage: 20,
+     *   where: { status: 'active' },
+     *   orderBy: ['createdAt', 'desc']
+     * })
+     */
+    static paginate<T extends typeof Model>(this: T, options?: PaginateOptions<TRecordFor<T>>, queryOptions?: ModelQueryOptions): Promise<PaginatedResult<TRecordFor<T>>>;
+    /**
+     * Paginate records with eager-loaded relationships.
+     *
+     * @param relations - Relation name(s) to load
+     * @param options - Pagination options
+     * @returns Paginated result with loaded relationships
+     *
+     * @example
+     * const result = await User.withPaginate('posts', { page: 1, perPage: 10 })
+     * // result.data - Users with their posts loaded
+     * // result.meta - Pagination metadata
+     */
+    static withPaginate<T extends typeof Model, K extends RelationKey<T>>(this: T, relations: K | readonly K[], options?: PaginateOptions<TRecordFor<T>>): Promise<PaginatedResult<TRecordFor<T> & RelationTypePick<T, K | readonly K[]>>>;
+    /**
+     * Create a new record.
+     *
+     * @param data - Record data to insert
+     * @returns The created record
+     *
+     * @example
+     * const user = await User.create({
+     *   name: 'John Doe',
+     *   email: 'john@example.com'
+     * })
+     */
+    static create<T extends typeof Model>(this: T, data: TCreateFor<T>, writeOptions?: ModelWriteOptions): Promise<TRecordFor<T>>;
+    /**
+     * Update records matching the conditions.
+     *
+     * @param where - Filter conditions to identify records
+     * @param data - Data to update
+     * @returns The updated record
+     *
+     * @example
+     * await User.update({ id: 1 }, { name: 'Jane Doe' })
+     */
+    static update<T extends typeof Model>(this: T, where: WhereClauseFor<T>, data: Partial<TCreateFor<T>>, writeOptions?: ModelWriteOptions): Promise<TRecordFor<T>>;
+    /**
+     * Delete records matching the conditions.
+     *
+     * @param where - Filter conditions to identify records
+     * @returns Number of deleted records or void depending on adapter
+     *
+     * @example
+     * await User.delete({ id: 1 })
+     * await User.delete({ status: 'inactive' })
+     */
+    static delete<T extends typeof Model>(this: T, where: WhereClauseFor<T>, writeOptions?: ModelWriteOptions): Promise<number | PlainObject | void>;
+    /**
+     * Get a raw Drizzle query builder for complex queries.
+     *
+     * @param db - Optional Drizzle database instance
+     * @returns Drizzle query builder starting with `select().from(table)`
+     *
+     * @example
+     * // Simple query
+     * const users = await User.query(db)
+     *   .where(eq(users.status, 'active'))
+     *   .limit(10)
+     *
+     * // With joins
+     * const usersWithPosts = await User.query(db)
+     *   .leftJoin(posts, eq(users.id, posts.userId))
+     */
+    static query<TDatabase extends {
+        select: (...args: any[]) => any;
+    } = {
+        select: (...args: any[]) => any;
+    }>(// eslint-disable-line @typescript-eslint/no-explicit-any
+    this: typeof Model, db?: TDatabase): SelectFrom<TDatabase>;
+    /**
+     * Eager-load relationships on records.
+     *
+     * @param relations - Relation name(s) to load
+     * @param where - Optional filter conditions
+     * @returns Records with loaded relationships
+     *
+     * @example
+     * // Single relation
+     * const usersWithPosts = await User.with('posts')
+     *
+     * // Multiple relations
+     * const usersWithAll = await User.with(['posts', 'comments'])
+     *
+     * // With filtering
+     * const activeUsersWithPosts = await User.with('posts', { status: 'active' })
+     */
+    static with<T extends typeof Model, K extends RelationKey<T>>(this: T, relations: K | readonly K[], where?: WhereClauseFor<T>): Promise<Array<TRecordFor<T> & RelationTypePick<T, K | readonly K[]>>>;
+    /** @internal Used by QueryBuilder for eager loading. */
+    static loadRelationInto<T extends typeof Model>(this: T, records: Array<PlainObject>, relationName: string): Promise<void>;
+    protected static loadHasMany(records: Array<PlainObject>, definition: HasManyRelationDefinition): Promise<void>;
+    protected static loadHasOne(records: Array<PlainObject>, definition: HasOneRelationDefinition): Promise<void>;
+    protected static loadBelongsTo(records: Array<PlainObject>, definition: BelongsToRelationDefinition): Promise<void>;
+    protected static loadBelongsToMany(records: Array<PlainObject>, definition: BelongsToManyRelationDefinition): Promise<void>;
+    protected static loadHasManyThrough(records: Array<PlainObject>, definition: HasManyThroughRelationDefinition): Promise<void>;
+    protected static loadMorphMany(records: Array<PlainObject>, definition: MorphManyRelationDefinition): Promise<void>;
+    protected static loadMorphTo(records: Array<PlainObject>, definition: MorphToRelationDefinition): Promise<void>;
+}
+type TRecordFor<T extends typeof Model> = T extends {
+    recordType: infer R;
+} ? R extends PlainObject ? R : PlainObject : PlainObject;
+type TCreateFor<T extends typeof Model> = T extends {
+    createType: infer R;
+} ? R extends PlainObject ? R : PlainObject : PlainObject;
+type WhereClauseFor<T extends typeof Model> = WhereClause<TRecordFor<T>>;
+type FieldFor<T extends typeof Model> = keyof TRecordFor<T> & string;
+type RelationTypesFor<T extends typeof Model> = T extends {
+    relationTypes: infer R;
+} ? R extends RelationShape ? R : {} : {};
+type RelationKey<T extends typeof Model> = keyof RelationTypesFor<T> & string;
+type RelationKeyOrString<T extends typeof Model> = RelationKey<T> extends never ? string : RelationKey<T>;
+type RelationNameUnion<Names> = Names extends readonly (infer Items)[] ? Items : Names;
+type RelationTypePick<T extends typeof Model, Names> = RelationNameUnion<Names> extends infer Keys ? Keys extends string ? {
+    [K in Keys & keyof RelationTypesFor<T>]: RelationTypesFor<T>[K];
+} : {} : {};
+interface TransactionModelScope<T extends typeof Model> {
+    readonly trx: TransactionHandle;
+    all(): Promise<TRecordFor<T>[]>;
+    find(id: unknown): Promise<TRecordFor<T> | null>;
+    findOrFail(id: unknown): Promise<TRecordFor<T>>;
+    first(where?: WhereClauseFor<T>): Promise<TRecordFor<T> | null>;
+    where(conditions: WhereClauseFor<T>): QueryBuilder<TRecordFor<T>>;
+    where(field: FieldFor<T>, value: unknown): QueryBuilder<TRecordFor<T>>;
+    where(field: FieldFor<T>, operator: WhereOperator, value: unknown): QueryBuilder<TRecordFor<T>>;
+    newQuery(): QueryBuilder<TRecordFor<T>>;
+    create(data: TCreateFor<T>): Promise<TRecordFor<T>>;
+    update(where: WhereClauseFor<T>, data: Partial<TCreateFor<T>>): Promise<TRecordFor<T>>;
+    delete(where: WhereClauseFor<T>): Promise<number | PlainObject | void>;
+    paginate(options?: PaginateOptions<TRecordFor<T>>): Promise<PaginatedResult<TRecordFor<T>>>;
+}
+interface BaseRelationDefinition {
+    type: 'hasMany' | 'hasOne' | 'belongsTo' | 'belongsToMany' | 'hasManyThrough' | 'morphMany' | 'morphTo';
+    name: string;
+    related: typeof Model | (() => typeof Model | Promise<typeof Model>);
+}
+interface HasManyRelationDefinition extends BaseRelationDefinition {
+    type: 'hasMany';
+    foreignKey: string;
+    localKey: string;
+}
+interface HasOneRelationDefinition extends BaseRelationDefinition {
+    type: 'hasOne';
+    foreignKey: string;
+    localKey: string;
+}
+interface BelongsToRelationDefinition extends BaseRelationDefinition {
+    type: 'belongsTo';
+    foreignKey: string;
+    ownerKey: string;
+}
+interface BelongsToManyRelationDefinition extends BaseRelationDefinition {
+    type: 'belongsToMany';
+    pivotTable: unknown;
+    foreignPivotKey: string;
+    relatedPivotKey: string;
+    parentKey: string;
+    relatedKey: string;
+}
+interface HasManyThroughRelationDefinition extends BaseRelationDefinition {
+    type: 'hasManyThrough';
+    through: typeof Model | (() => typeof Model | Promise<typeof Model>);
+    firstKey: string;
+    secondKey: string;
+    localKey: string;
+    secondLocalKey: string;
+}
+type RelationDefinition = HasManyRelationDefinition | HasOneRelationDefinition | BelongsToRelationDefinition | BelongsToManyRelationDefinition | HasManyThroughRelationDefinition | MorphManyRelationDefinition | MorphToRelationDefinition;
+interface MorphManyRelationDefinition extends BaseRelationDefinition {
+    type: 'morphMany';
+    morphName: string;
+    localKey: string;
+}
+interface MorphToRelationDefinition {
+    type: 'morphTo';
+    name: string;
+    related: undefined;
+    morphName: string;
+}
+
+type SessionData = Record<string, unknown>;
+interface SessionStore {
+    /**
+     * Read a session by its opaque identifier.
+     * Returns undefined when the session does not exist or has expired.
+     */
+    read(id: string): Promise<SessionData | undefined>;
+    /**
+     * Persist a session using upsert semantics for the given opaque identifier.
+     */
+    write(id: string, data: SessionData, ttlSeconds: number): Promise<void>;
+    /**
+     * Destroy a session. Implementations must treat repeated calls as safe.
+     */
+    destroy(id: string): Promise<void>;
+}
+declare class MemorySessionStore implements SessionStore {
+    private readonly now;
+    private readonly store;
+    constructor(now?: () => number);
+    read(id: string): Promise<SessionData | undefined>;
+    write(id: string, data: SessionData, ttlSeconds: number): Promise<void>;
+    destroy(id: string): Promise<void>;
+}
+interface SessionOptions {
+    cookieName?: string;
+    cookiePath?: string;
+    cookieDomain?: string;
+    cookieSecure?: boolean;
+    cookieSameSite?: 'Strict' | 'Lax' | 'None';
+    cookieHttpOnly?: boolean;
+    cookieMaxAgeSeconds?: number;
+    ttlSeconds?: number;
+    store?: SessionStore;
+}
+interface Session {
+    readonly id: string;
+    readonly isNew: boolean;
+    get<T = unknown>(key: string): T | undefined;
+    set<T = unknown>(key: string, value: T): void;
+    has(key: string): boolean;
+    forget(key: string): void;
+    flush(): void;
+    all(): SessionData;
+    regenerate(): void;
+    invalidate(): void;
+    flash(key: string, value: unknown): void;
+    getFlash<T = unknown>(key: string): T | undefined;
+    reflash(): void;
+    keep(...keys: string[]): void;
+}
+interface CreateSessionMiddlewareOptions extends SessionOptions {
+}
+declare function createSessionMiddleware(options?: CreateSessionMiddlewareOptions): MiddlewareHandler;
+declare function getSessionFromContext<T extends Session = Session>(ctx: {
+    get: (key: string) => unknown;
+}): T | undefined;
+
+type AuthCredentials = Record<string, unknown>;
+interface Authenticatable {
+    getAuthIdentifier(): unknown;
+    getAuthPassword(): string | null | undefined;
+    getRememberToken?(): string | null | undefined;
+    setRememberToken?(token: string | null): void | Promise<void>;
+}
+interface Guard<User = Authenticatable> {
+    check(): Promise<boolean>;
+    guest(): Promise<boolean>;
+    user<T = User>(): Promise<T | null>;
+    id(): Promise<unknown>;
+    login<T = User>(user: T, remember?: boolean): Promise<void>;
+    logout(): Promise<void>;
+    attempt(credentials: AuthCredentials, remember?: boolean): Promise<boolean>;
+    validate(credentials: AuthCredentials): Promise<User | null>;
+    session<T extends Session = Session>(): T | undefined;
+}
+interface UserProvider<User = Authenticatable> {
+    retrieveById(identifier: unknown): Promise<User | null>;
+    retrieveByCredentials(credentials: AuthCredentials): Promise<User | null>;
+    validateCredentials(user: User, credentials: AuthCredentials): Promise<boolean>;
+    getId(user: User): unknown;
+    setRememberToken?(user: User, token: string | null): Promise<void> | void;
+    getRememberToken?(user: User): Promise<string | null> | string | null;
+}
+interface GuardContext {
+    ctx: Context;
+    session: Session | undefined;
+    manager: AuthManagerContract;
+}
+type GuardFactory<User = Authenticatable> = (context: GuardContext) => Guard<User>;
+interface ProviderFactory<User = Authenticatable> {
+    (manager: AuthManagerContract): UserProvider<User>;
+}
+interface AuthManagerOptions {
+    defaultGuard?: string;
+}
+interface AttachContextOptions {
+    guard?: string;
+}
+interface AuthContext<User = Authenticatable> {
+    check(): Promise<boolean>;
+    guest(): Promise<boolean>;
+    user<T = User>(): Promise<T | null>;
+    userOrFail<T = User>(): Promise<T>;
+    id(): Promise<unknown>;
+    login<T = User>(user: T, remember?: boolean): Promise<void>;
+    attempt(credentials: AuthCredentials, remember?: boolean): Promise<boolean>;
+    logout(): Promise<void>;
+    guard<T = User>(name?: string): Guard<T>;
+    session<T extends Session = Session>(): T | undefined;
+}
+interface AuthManagerContract {
+    registerGuard<User = Authenticatable>(name: string, factory: GuardFactory<User>): void;
+    registerProvider<User = Authenticatable>(name: string, factory: ProviderFactory<User>): void;
+    getProvider<User = Authenticatable>(name: string): UserProvider<User>;
+    createGuard<User = Authenticatable>(name: string, context: GuardContext): Guard<User>;
+    guardNames(): string[];
+    setDefaultGuard(name: string): void;
+    getDefaultGuard(): string;
+    createAuthContext(ctx: Context, options?: AttachContextOptions): AuthContext;
+}
+
+interface PasswordHasher {
+    hash(plain: string): Promise<string>;
+    verify(hashed: string, plain: string): Promise<boolean>;
+    needsRehash?(hashed: string): boolean;
+}
+
+declare abstract class BaseUserProvider<User extends Authenticatable = Authenticatable> implements UserProvider<User> {
+    abstract retrieveById(identifier: unknown): Promise<User | null>;
+    abstract retrieveByCredentials(credentials: AuthCredentials): Promise<User | null>;
+    abstract validateCredentials(user: User, credentials: AuthCredentials): Promise<boolean>;
+    abstract getId(user: User): unknown;
+    setRememberToken(user: User, token: string | null): Promise<void>;
+    getRememberToken(user: User): Promise<string | null>;
+}
+
+interface ModelUserProviderOptions {
+    idColumn?: string;
+    usernameColumn?: string;
+    passwordColumn?: string;
+    rememberTokenColumn?: string;
+    hasher?: PasswordHasher;
+    credentialsPasswordField?: string;
+}
+declare class ModelUserProvider<User extends Authenticatable = Authenticatable> extends BaseUserProvider<User> {
+    private readonly model;
+    private readonly idColumn;
+    private readonly usernameColumn;
+    private readonly passwordColumn;
+    private readonly rememberTokenColumn;
+    private readonly hasher;
+    private readonly credentialsPasswordField;
+    constructor(model: typeof Model, options?: ModelUserProviderOptions);
+    private cast;
+    retrieveById(identifier: unknown): Promise<User | null>;
+    retrieveByCredentials(credentials: AuthCredentials): Promise<User | null>;
+    validateCredentials(user: User, credentials: AuthCredentials): Promise<boolean>;
+    getId(user: User): unknown;
+    setRememberToken(user: User, token: string | null): Promise<void>;
+    getRememberToken(user: User): Promise<string | null>;
+}
+
+declare class AuthManager implements AuthManagerContract {
+    private readonly guards;
+    private readonly providers;
+    private defaultGuard;
+    constructor(options?: AuthManagerOptions);
+    registerGuard<User>(name: string, factory: GuardFactory<User>): void;
+    registerProvider<User>(name: string, factory: ProviderFactory<User>): void;
+    getProvider<User>(name: string): UserProvider<User>;
+    createGuard<User>(name: string, context: GuardContext): Guard<User>;
+    guardNames(): string[];
+    setDefaultGuard(name: string): void;
+    getDefaultGuard(): string;
+    createAuthContext(ctx: Context, options?: AttachContextOptions): AuthContext;
+    attempt(name: string, ctx: Context, credentials: AuthCredentials, remember?: boolean): Promise<boolean>;
+    /**
+     * Shorthand method to register a model-based authentication provider and session guard.
+     * This simplifies the common case of authenticating users via a database model.
+     *
+     * @param model - The model class to use for user authentication
+     * @param options - Options for the ModelUserProvider (partial, with defaults)
+     * @param providerName - Name for the provider (defaults to 'users')
+     * @param guardName - Name for the guard (defaults to 'web')
+     */
+    useModel(model: typeof Model<PlainObject>, options?: Partial<ModelUserProviderOptions>, providerName?: string, guardName?: string): void;
+}
+
+interface OAuthProviderConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    authorizeUrl: string;
+    tokenUrl: string;
+    userInfoUrl: string;
+    scopes?: string[];
+    tokenAuthMethod?: 'client_secret_post' | 'client_secret_basic';
+    userInfoMethod?: 'GET' | 'POST';
+    mapProfile?: (raw: Record<string, unknown>, token: OAuthTokenResult) => OAuthUserProfile;
+}
+interface OAuthTokenResult {
+    accessToken: string;
+    tokenType?: string;
+    refreshToken?: string;
+    expiresIn?: number;
+    scope?: string;
+    raw: Record<string, unknown>;
+}
+interface OAuthUserProfile {
+    id: string;
+    email?: string;
+    name?: string;
+    avatar?: string;
+    token: OAuthTokenResult;
+    raw: Record<string, unknown>;
+}
+interface OAuthStatePayload {
+    provider: string;
+    redirectTo?: string;
+    expiresAt: Date;
+}
+interface OAuthStateStore {
+    store(stateHash: string, payload: OAuthStatePayload): Promise<void>;
+    find(stateHash: string): Promise<OAuthStatePayload | null>;
+    delete(stateHash: string): Promise<void>;
+}
+interface OAuthStateConfig {
+    expiresIn?: number;
+    stateLength?: number;
+    hashAlgorithm?: 'sha256' | 'sha512';
+}
+interface OAuthAuthorizeOptions {
+    scope?: string[];
+    redirectTo?: string;
+    state?: string;
+    extraParams?: Record<string, string>;
+}
+interface OAuthCallbackPayload {
+    code: string;
+    state: string;
+}
+interface OAuthManagerOptions {
+    stateStore?: OAuthStateStore;
+    stateConfig?: OAuthStateConfig;
+}
+declare class MemoryOAuthStateStore implements OAuthStateStore {
+    private readonly states;
+    store(stateHash: string, payload: OAuthStatePayload): Promise<void>;
+    find(stateHash: string): Promise<OAuthStatePayload | null>;
+    delete(stateHash: string): Promise<void>;
+    clear(): void;
+}
+declare class OAuthManager {
+    private readonly providers;
+    private readonly stateStore;
+    private readonly stateConfig;
+    constructor(options?: OAuthManagerOptions);
+    registerProvider(name: string, config: OAuthProviderConfig): void;
+    providerNames(): string[];
+    getProvider(name: string): OAuthProviderConfig;
+    authorize(providerName: string, options?: OAuthAuthorizeOptions): Promise<{
+        url: string;
+        state: string;
+        expiresAt: Date;
+    }>;
+    user(providerName: string, payload: OAuthCallbackPayload): Promise<OAuthUserProfile>;
+}
+declare function createOAuthManager(options?: OAuthManagerOptions): OAuthManager;
+declare function createOAuthState(provider: string, store: OAuthStateStore, config?: OAuthStateConfig, redirectTo?: string, fixedState?: string): Promise<{
+    state: string;
+    expiresAt: Date;
+}>;
+declare function verifyOAuthState(state: string, provider: string, store: OAuthStateStore, config?: OAuthStateConfig): Promise<OAuthStatePayload | null>;
+declare function buildOAuthAuthorizeUrl(provider: OAuthProviderConfig, state: string, options?: {
+    scope?: string[];
+    extraParams?: Record<string, string>;
+}): string;
+declare function exchangeOAuthCode(provider: OAuthProviderConfig, code: string): Promise<OAuthTokenResult>;
+declare function fetchOAuthUserProfile(provider: OAuthProviderConfig, token: OAuthTokenResult): Promise<OAuthUserProfile>;
+interface OAuthProviderFactoryInput {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes?: string[];
+}
+declare function createGitHubOAuthProviderConfig(input: OAuthProviderFactoryInput): OAuthProviderConfig;
+declare function createGoogleOAuthProviderConfig(input: OAuthProviderFactoryInput): OAuthProviderConfig;
+declare function createDiscordOAuthProviderConfig(input: OAuthProviderFactoryInput): OAuthProviderConfig;
+declare function buildOAuthRedirectUrl(baseUrl: string, token: string, email?: string): string;
+declare function parseOAuthRedirectUrl(url: string): {
+    token: string | null;
+    email: string | null;
+};
+
+/**
+ * API token data stored in the backing store.
+ */
+interface ApiToken {
+    id: string;
+    name: string;
+    hashedToken: string;
+    userId: string | number;
+    abilities: string[];
+    lastUsedAt: Date | null;
+    expiresAt: Date | null;
+    createdAt: Date;
+}
+/**
+ * Store interface for API tokens.
+ * Implement this for database-backed storage.
+ */
+interface ApiTokenStore {
+    /**
+     * Store a new API token.
+     */
+    store(token: ApiToken): Promise<void>;
+    /**
+     * Find a token by its hashed value.
+     */
+    findByHashedToken(hashedToken: string): Promise<ApiToken | null>;
+    /**
+     * Find all tokens for a user.
+     */
+    findByUserId(userId: string | number): Promise<ApiToken[]>;
+    /**
+     * Delete a token by its ID.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Delete all tokens for a user.
+     */
+    deleteForUser(userId: string | number): Promise<void>;
+    /**
+     * Update the last used timestamp.
+     */
+    updateLastUsed(id: string, timestamp: Date): Promise<void>;
+}
+/**
+ * In-memory token store for testing.
+ * Do NOT use in production - tokens will be lost on restart.
+ */
+declare class MemoryApiTokenStore implements ApiTokenStore {
+    private tokens;
+    private byHash;
+    store(token: ApiToken): Promise<void>;
+    findByHashedToken(hashedToken: string): Promise<ApiToken | null>;
+    findByUserId(userId: string | number): Promise<ApiToken[]>;
+    delete(id: string): Promise<void>;
+    deleteForUser(userId: string | number): Promise<void>;
+    updateLastUsed(id: string, timestamp: Date): Promise<void>;
+    /**
+     * Clear all tokens (useful for testing).
+     */
+    clear(): void;
+    /**
+     * Get the number of stored tokens.
+     */
+    get size(): number;
+}
+/**
+ * Configuration for API token creation.
+ */
+interface CreateApiTokenOptions {
+    /**
+     * Human-readable name for the token.
+     */
+    name: string;
+    /**
+     * User ID the token belongs to.
+     */
+    userId: string | number;
+    /**
+     * Token abilities/scopes.
+     * @default ['*'] (all abilities)
+     */
+    abilities?: string[];
+    /**
+     * Token expiration time in milliseconds from now.
+     * @default null (never expires)
+     */
+    expiresIn?: number | null;
+    /**
+     * Token byte length (before encoding).
+     * @default 32
+     */
+    tokenLength?: number;
+}
+/**
+ * Result of creating an API token.
+ */
+interface CreateApiTokenResult {
+    /**
+     * The full token to give to the user.
+     * Format: {id}|{plainToken}
+     * This is the ONLY time the plain token is available.
+     */
+    plainTextToken: string;
+    /**
+     * The token record (without the plain token).
+     */
+    token: ApiToken;
+}
+/**
+ * Create a new API token.
+ *
+ * @example
+ * ```ts
+ * const { plainTextToken, token } = await createApiToken(store, {
+ *   name: 'My App Token',
+ *   userId: user.id,
+ *   abilities: ['read', 'write'],
+ *   expiresIn: 30 * 24 * 60 * 60 * 1000, // 30 days
+ * })
+ *
+ * // Return plainTextToken to user - this is the only time it's available
+ * return ctx.json({ token: plainTextToken })
+ * ```
+ */
+declare function createApiToken(store: ApiTokenStore, options: CreateApiTokenOptions): Promise<CreateApiTokenResult>;
+/**
+ * Parse a plain text token into its components.
+ */
+declare function parseApiToken(plainTextToken: string): {
+    id: string;
+    token: string;
+} | null;
+/**
+ * Verify an API token and return the associated user ID.
+ *
+ * @example
+ * ```ts
+ * const result = await verifyApiToken(plainTextToken, store)
+ *
+ * if (!result) {
+ *   return ctx.json({ error: 'Invalid token' }, 401)
+ * }
+ *
+ * console.log(`User ${result.userId} authenticated with abilities:`, result.abilities)
+ * ```
+ */
+declare function verifyApiToken(plainTextToken: string, store: ApiTokenStore, options?: {
+    updateLastUsed?: boolean;
+}): Promise<{
+    token: ApiToken;
+    userId: string | number;
+    abilities: string[];
+} | null>;
+/**
+ * Check if a token has a specific ability.
+ */
+declare function tokenCan(token: ApiToken | {
+    abilities: string[];
+}, ability: string): boolean;
+/**
+ * Check if a token has all specified abilities.
+ */
+declare function tokenCanAll(token: ApiToken | {
+    abilities: string[];
+}, abilities: string[]): boolean;
+/**
+ * Check if a token has any of the specified abilities.
+ */
+declare function tokenCanAny(token: ApiToken | {
+    abilities: string[];
+}, abilities: string[]): boolean;
+/**
+ * Revoke (delete) an API token.
+ *
+ * @example
+ * ```ts
+ * await revokeApiToken(tokenId, store)
+ * ```
+ */
+declare function revokeApiToken(id: string, store: ApiTokenStore): Promise<void>;
+/**
+ * Revoke all API tokens for a user.
+ *
+ * @example
+ * ```ts
+ * // Revoke all tokens when user changes password
+ * await revokeAllApiTokens(user.id, store)
+ * ```
+ */
+declare function revokeAllApiTokens(userId: string | number, store: ApiTokenStore): Promise<void>;
+/**
+ * Get all API tokens for a user.
+ *
+ * @example
+ * ```ts
+ * const tokens = await getUserApiTokens(user.id, store)
+ * // Returns tokens without the plain text (only metadata)
+ * ```
+ */
+declare function getUserApiTokens(userId: string | number, store: ApiTokenStore): Promise<ApiToken[]>;
+/**
+ * Context key for storing the authenticated token.
+ */
+declare const API_TOKEN_KEY = "guren:api-token";
+/**
+ * Options for the bearer token middleware.
+ */
+interface BearerTokenMiddlewareOptions {
+    /**
+     * Token store implementation.
+     */
+    store: ApiTokenStore;
+    /**
+     * Function to load the user from the user ID.
+     */
+    loadUser?: (userId: string | number) => Promise<unknown>;
+    /**
+     * Required abilities for this route.
+     * If not specified, any valid token is accepted.
+     */
+    abilities?: string[];
+    /**
+     * Custom handler when authentication fails.
+     */
+    onUnauthorized?: (ctx: Context) => Response | Promise<Response>;
+    /**
+     * Custom handler when token lacks required abilities.
+     */
+    onForbidden?: (ctx: Context, required: string[]) => Response | Promise<Response>;
+    /**
+     * Header name to extract the token from.
+     * @default 'Authorization'
+     */
+    headerName?: string;
+    /**
+     * Whether to update the token's lastUsedAt timestamp.
+     * @default true
+     */
+    updateLastUsed?: boolean;
+}
+/**
+ * Create middleware that authenticates requests using Bearer tokens.
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * app.use('/api/*', createBearerTokenMiddleware({ store }))
+ *
+ * // With ability requirement
+ * router.delete('/api/posts/:id', [PostController, 'destroy'],
+ *   createBearerTokenMiddleware({
+ *     store,
+ *     abilities: ['posts:delete'],
+ *   })
+ * )
+ *
+ * // With user loading
+ * app.use('/api/*', createBearerTokenMiddleware({
+ *   store,
+ *   loadUser: async (userId) => User.find(userId),
+ * }))
+ * ```
+ */
+declare function createBearerTokenMiddleware(options: BearerTokenMiddlewareOptions): MiddlewareHandler;
+/**
+ * Get the authenticated API token from the request context.
+ *
+ * @example
+ * ```ts
+ * router.get('/api/me', async (ctx) => {
+ *   const { token, userId, abilities } = getApiToken(ctx)!
+ *   return ctx.json({ userId, tokenName: token.name, abilities })
+ * })
+ * ```
+ */
+declare function getApiToken(ctx: Context): {
+    token: ApiToken;
+    userId: string | number;
+    abilities: string[];
+} | null;
+/**
+ * Get the authenticated API token from the request context, or throw.
+ *
+ * @throws {AuthenticationException} When no token is present in the context.
+ *
+ * @example
+ * ```ts
+ * router.get('/api/me', async (ctx) => {
+ *   const { token, userId, abilities } = getApiTokenOrFail(ctx)
+ *   return ctx.json({ userId, tokenName: token.name, abilities })
+ * })
+ * ```
+ */
+declare function getApiTokenOrFail(ctx: Context): {
+    token: ApiToken;
+    userId: string | number;
+    abilities: string[];
+};
+
+export { parseOAuthRedirectUrl as $, AuthManager as A, BaseUserProvider as B, type CreateSessionMiddlewareOptions as C, type SessionStore as D, buildOAuthAuthorizeUrl as E, buildOAuthRedirectUrl as F, type Guard as G, createApiToken as H, createBearerTokenMiddleware as I, createDiscordOAuthProviderConfig as J, createGitHubOAuthProviderConfig as K, createGoogleOAuthProviderConfig as L, MemoryApiTokenStore as M, createOAuthManager as N, OAuthManager as O, type ProviderFactory as P, createOAuthState as Q, createSessionMiddleware as R, type Session as S, exchangeOAuthCode as T, type UserProvider as U, fetchOAuthUserProfile as V, getApiToken as W, getApiTokenOrFail as X, getSessionFromContext as Y, getUserApiTokens as Z, parseApiToken as _, type AuthContext as a, revokeAllApiTokens as a0, revokeApiToken as a1, tokenCan as a2, tokenCanAll as a3, tokenCanAny as a4, verifyApiToken as a5, verifyOAuthState as a6, type PasswordHasher as a7, type PlainObject as a8, Model as a9, type AttachContextOptions as aa, type AuthManagerContract as ab, type ApiToken as b, API_TOKEN_KEY as c, type ApiTokenStore as d, type AuthCredentials as e, type AuthManagerOptions as f, type Authenticatable as g, type BearerTokenMiddlewareOptions as h, type CreateApiTokenOptions as i, type CreateApiTokenResult as j, type GuardContext as k, type GuardFactory as l, MemoryOAuthStateStore as m, MemorySessionStore as n, ModelUserProvider as o, type OAuthAuthorizeOptions as p, type OAuthCallbackPayload as q, type OAuthManagerOptions as r, type OAuthProviderConfig as s, type OAuthProviderFactoryInput as t, type OAuthStateConfig as u, type OAuthStatePayload as v, type OAuthStateStore as w, type OAuthTokenResult as x, type OAuthUserProfile as y, type SessionData as z };