@active-record-ts/active-model 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,766 @@
+/**
+ * Type system for ActiveModel attributes.
+ *
+ * Each Type owns three coercion functions:
+ *  - `cast` converts a value coming from user code (`record.name = 1`)
+ *    into the canonical attribute value (e.g. `"1"` for a string column).
+ *  - `serialize` converts an attribute value into a driver-compatible
+ *    value for INSERT/UPDATE statements.
+ *  - `deserialize` converts a value coming back from the driver into an
+ *    attribute value.
+ *
+ * The named type registry mirrors Rails' `ActiveModel::Type` registry.
+ * Adapters can register adapter-specific types (e.g. PostgreSQL's `uuid`
+ * or `jsonb`) by calling `Type.register(name, factory)`.
+ */
+/** Base interface every type implementation satisfies. */
+interface Type<T = unknown> {
+    /** Name of the type as registered (e.g. `'string'`, `'integer'`). */
+    readonly type: string;
+    cast(value: unknown): T | null;
+    serialize(value: T | null): unknown;
+    deserialize(value: unknown): T | null;
+    /** Returns true when the two values represent the same logical attribute value. */
+    equals?(a: T | null, b: T | null): boolean;
+}
+declare class StringType implements Type<string> {
+    readonly type = "string";
+    cast(value: unknown): string | null;
+    serialize(value: string | null): string | null;
+    deserialize(value: unknown): string | null;
+}
+declare class IntegerType implements Type<number> {
+    readonly type = "integer";
+    cast(value: unknown): number | null;
+    serialize(value: number | null): number | null;
+    deserialize(value: unknown): number | null;
+}
+declare class BigIntType implements Type<bigint> {
+    readonly type = "bigint";
+    cast(value: unknown): bigint | null;
+    serialize(value: bigint | null): bigint | null;
+    deserialize(value: unknown): bigint | null;
+}
+declare class FloatType implements Type<number> {
+    readonly type = "float";
+    cast(value: unknown): number | null;
+    serialize(value: number | null): number | null;
+    deserialize(value: unknown): number | null;
+}
+/**
+ * Stored as a string to preserve precision. Drivers commonly return decimals
+ * as strings; we keep them that way for callers to feed into a decimal lib
+ * of choice (we don't ship one).
+ */
+declare class DecimalType implements Type<string> {
+    readonly type = "decimal";
+    cast(value: unknown): string | null;
+    serialize(value: string | null): string | null;
+    deserialize(value: unknown): string | null;
+}
+declare class BooleanType implements Type<boolean> {
+    readonly type = "boolean";
+    cast(value: unknown): boolean | null;
+    serialize(value: boolean | null): boolean | null;
+    deserialize(value: unknown): boolean | null;
+}
+declare class DateType implements Type<Date> {
+    readonly type = "date";
+    cast(value: unknown): Date | null;
+    serialize(value: Date | null): string | null;
+    deserialize(value: unknown): Date | null;
+    equals(a: Date | null, b: Date | null): boolean;
+}
+declare class DateTimeType implements Type<Date> {
+    readonly type = "datetime";
+    cast(value: unknown): Date | null;
+    serialize(value: Date | null): string | null;
+    deserialize(value: unknown): Date | null;
+    equals(a: Date | null, b: Date | null): boolean;
+}
+declare class JSONType<T = unknown> implements Type<T> {
+    readonly type = "json";
+    cast(value: unknown): T | null;
+    serialize(value: T | null): string | null;
+    deserialize(value: unknown): T | null;
+}
+declare class BinaryType implements Type<Uint8Array> {
+    readonly type = "binary";
+    cast(value: unknown): Uint8Array | null;
+    serialize(value: Uint8Array | null): Uint8Array<ArrayBufferLike> | null;
+    deserialize(value: unknown): Uint8Array | null;
+    equals(a: Uint8Array | null, b: Uint8Array | null): boolean;
+}
+/**
+ * Pass-through type for unmapped or adapter-specific values. Used as the
+ * default when schema reflection finds a column type we don't know about.
+ */
+declare class ValueType implements Type<unknown> {
+    readonly type = "value";
+    cast(value: unknown): unknown;
+    serialize(value: unknown): unknown;
+    deserialize(value: unknown): unknown;
+}
+/** Compare two values via the type's `equals` hook if present, else `===`. */
+declare const valuesEqual: <T>(type: Type<T>, a: T | null, b: T | null) => boolean;
+type Factory = () => Type;
+/** Register a named type (factory invoked per `Type.lookup`). */
+declare const registerType: (name: string, factory: Factory) => void;
+/** Resolve a named type. Throws if unregistered. */
+declare const lookupType: (name: string) => Type;
+/** True when the named type has been registered. */
+declare const hasType: (name: string) => boolean;
+
+/**
+ * Per-instance attribute storage with dirty tracking.
+ *
+ * Two layers of values:
+ *   - `original` — the value when the record was loaded from the DB (or
+ *     last `save`/`commit`). Used to compute the dirty diff.
+ *   - `current` — the working value, updated by every assignment.
+ *
+ * Dirty surface (mirrors Rails' `ActiveModel::Dirty`):
+ *   - `changed()`        — list of attribute names that differ from original
+ *   - `changes()`        — `{ name: [from, to] }` map of pending changes
+ *   - `attributeChanged(name)` — boolean
+ *   - `attributeWas(name)`     — original value
+ *   - `savedChanges()`         — changes that were applied during the last save
+ *   - `attributePreviouslyChanged(name)` — boolean (post-save introspection)
+ */
+
+/** Declaration of a single attribute on a model. */
+type AttributeDefinition = {
+    name: string;
+    type: Type;
+    /** Default applied when a record is new and the attribute is not assigned. */
+    default?: unknown;
+};
+declare class AttributeSet {
+    private readonly definitions;
+    /** Insertion-ordered list of attribute names, for stable iteration. */
+    private readonly names;
+    /** Register an attribute (or replace an existing one). */
+    define(definition: AttributeDefinition): void;
+    has(name: string): boolean;
+    get(name: string): AttributeDefinition | undefined;
+    keys(): string[];
+    /** Stable iteration of definitions in declaration order. */
+    [Symbol.iterator](): IterableIterator<AttributeDefinition>;
+    size(): number;
+    clone(): AttributeSet;
+}
+/** Per-instance attribute state — values + originals + last-save snapshot. */
+declare class Attributes {
+    private readonly set;
+    private readonly current;
+    private readonly original;
+    private previousChanges;
+    private readonly accessedNames;
+    constructor(set: AttributeSet);
+    /** Hydrate attributes after loading from the DB. Skips dirty tracking. */
+    hydrate(raw: Record<string, unknown>): void;
+    /** Hydrate attributes for a brand-new record (applies defaults). */
+    hydrateDefaults(overrides?: Record<string, unknown>): void;
+    /** Read an attribute by name, returning the canonical (cast) value. */
+    read(name: string): unknown;
+    /** Names that have been read since hydration. Mirrors Rails' `accessed_attributes`. */
+    accessed(): string[];
+    /** Write an attribute by name. Type-casts before storing. */
+    write(name: string, value: unknown): void;
+    /**
+     * Explicitly mark `name` as having been mutated in place — without
+     * actually writing a new value. Mirrors Rails' `name_will_change!`
+     * which captures the current value into the original snapshot for
+     * later mutation detection.
+     */
+    willChange(name: string): void;
+    /** Was this attribute changed since the last commit? */
+    changed(name: string): boolean;
+    /** List of attribute names that differ from their originals. */
+    changedAttributes(): string[];
+    /** `{ name: [from, to] }` for every changed attribute. */
+    changes(): Record<string, [unknown, unknown]>;
+    /** Original value of `name` (current value if unchanged). */
+    was(name: string): unknown;
+    /** Snapshot for SAVE — return the canonical values for each attribute. */
+    toHash(): Record<string, unknown>;
+    /** Snapshot of only the dirty attributes (for UPDATE statements). */
+    dirtyHash(): Record<string, unknown>;
+    /** Serialized snapshot of all attributes (driver-ready values). */
+    serializedHash(): Record<string, unknown>;
+    /** Mark the current values as the new baseline. Captures previous changes. */
+    commit(): void;
+    /** Drop all pending and recorded changes — used by `clearChangesInformation`. */
+    clearChanges(): void;
+    /** Revert all pending changes. */
+    restore(): void;
+    /** Changes that were applied during the last `commit`. */
+    savedChanges(): Record<string, [unknown, unknown]>;
+    attributeSet(): AttributeSet;
+}
+
+/**
+ * Per-class callback chains for save/create/update/destroy/validation.
+ *
+ * Each chain holds an ordered list of callbacks. A `before` callback may
+ * abort the chain by returning `false`. `around` callbacks receive a
+ * `yield` function that runs the rest of the chain.
+ *
+ * The shape mirrors `ActiveSupport::Callbacks` enough to express Rails-y
+ * lifecycle hooks, without trying to be a general callback framework.
+ */
+type CallbackKind = 'before' | 'after' | 'around';
+type CallbackEvent = 'validation' | 'save' | 'create' | 'update' | 'destroy' | 'commit' | 'rollback' | 'initialize' | 'find' | 'touch';
+type CallbackFn<T> = (record: T) => void | boolean | Promise<void | boolean>;
+type AroundCallbackFn<T> = (record: T, run: () => Promise<void>) => Promise<void>;
+/** Sentinel — throw inside a callback to cleanly halt the chain. */
+declare class HaltError extends Error {
+    constructor();
+}
+/**
+ * Symbol-shaped sentinel callers can throw to halt the chain — mirrors
+ * Rails' `throw :abort` semantics. The chain swallows it and treats it
+ * as a `false` return from a `before_*` callback.
+ */
+declare const ABORT_SENTINEL: unique symbol;
+/** Convenience helper for chain implementations: convert "throw :abort" to a clean halt. */
+declare const throwAbort: () => never;
+declare class CallbackChain<T> {
+    private readonly chains;
+    /** Register a new callback under `event` of `kind`. */
+    add(event: CallbackEvent, kind: CallbackKind, fn: CallbackFn<T> | AroundCallbackFn<T>, options?: {
+        if?: (record: T) => boolean;
+        unless?: (record: T) => boolean;
+        on?: string | string[];
+    }): void;
+    /** Copy chains from a parent so subclasses inherit before extending. */
+    inheritFrom(parent: CallbackChain<T>): void;
+    /**
+     * Run the chain around `body`. Returns `false` when a `before` callback
+     * halts; otherwise returns the return value of `body`. Pass a `context`
+     * to filter callbacks registered with `on:` — primarily used for
+     * validation contexts (`create`/`update`) but available everywhere.
+     */
+    run(event: CallbackEvent, record: T, body: () => Promise<void | boolean>, context?: string): Promise<boolean>;
+}
+
+/**
+ * Error collection on a model instance. Mirrors `ActiveModel::Errors`
+ * minus i18n — message strings are stored verbatim. The full set of
+ * Rails behaviors we now support:
+ *
+ *   - `add(attribute, typeOrMessage, options?)` where the second argument
+ *     can be a known symbol-style type (e.g. `'blank'`, `'too_short'`)
+ *     that maps to a default message string, or a free-form message.
+ *   - `on(attribute)` returns the list of messages for an attribute.
+ *   - `attributeNames` returns the unique attributes carrying an error.
+ *   - `added(attribute, type?, options?)` predicate.
+ *   - `where(attribute, type?, options?)` returns the matching entries.
+ *   - `messagesFor` / `fullMessagesFor` with optional type filter.
+ *   - `merge(other)` / `copy(other)`.
+ */
+type ErrorEntry = {
+    attribute: string;
+    message: string;
+    /** Optional discriminator for the validator that produced this error. */
+    type?: string;
+    /** Optional structured payload, e.g. `{ count: 2 }` for length validators. */
+    options?: Record<string, unknown>;
+};
+/**
+ * Rich error object exposed by `errors.objects` / `errors.first` / iteration.
+ * Mirrors a subset of Rails' `ActiveModel::Error` — enough for callers
+ * who want to introspect (attribute / type / options / full message) rather
+ * than work with bare strings.
+ */
+declare class ErrorObject {
+    private readonly entry;
+    constructor(entry: ErrorEntry);
+    get attribute(): string;
+    get message(): string;
+    get type(): string | undefined;
+    get options(): Record<string, unknown> | undefined;
+    fullMessage(): string;
+    /** Internal accessor for `Errors#import` — returns the wrapped entry. */
+    toEntry(): ErrorEntry;
+}
+/** Special attribute name for errors that aren't tied to a specific column. */
+declare const BASE = "base";
+type AddOptions = {
+    type?: string;
+    options?: Record<string, unknown>;
+};
+declare class Errors {
+    private readonly entries;
+    /**
+     * Record an error. The second argument can be:
+     *  - a free-form message string (e.g. `errors.add('name', "can't be empty")`)
+     *  - a known symbol-style type that resolves to a default message
+     *    (e.g. `errors.add('name', 'blank')` -> "can't be blank")
+     *
+     * Pass extra interpolation values or a custom `type` via the third arg.
+     */
+    add(attribute: string, messageOrType?: string, options?: AddOptions & Record<string, unknown>): ErrorEntry;
+    /** True when there are no errors at all. */
+    get empty(): boolean;
+    /** True when at least one error has been recorded. */
+    get any(): boolean;
+    clear(): void;
+    delete(attribute: string, type?: string, matchOptions?: Record<string, unknown>): string[];
+    on(attribute: string): string[];
+    includes(attribute: string): boolean;
+    /** All `[attribute, message]` pairs, in insertion order. */
+    get messages(): Record<string, string[]>;
+    /** Distinct attributes that currently carry at least one error. */
+    get attributeNames(): string[];
+    /** Predicate: was an error matching the given attribute (and optional type / options) added? */
+    added(attribute: string, type?: string, matchOptions?: Record<string, unknown>): boolean;
+    /** Filter entries by attribute / type / options. */
+    where(attribute: string, type?: string, matchOptions?: Record<string, unknown>): ErrorEntry[];
+    /** Messages for a specific attribute, optionally filtered by type. */
+    messagesFor(attribute: string, type?: string): string[];
+    /** Human-readable strings like `"Name can't be blank"`. */
+    get fullMessages(): string[];
+    fullMessagesFor(attribute: string, type?: string): string[];
+    /** Standalone full-message formatter (no entries side effect). */
+    fullMessage(attribute: string, message: string): string;
+    /** Append every entry from `other` to this collection. */
+    merge(other: Errors): this;
+    /** Replace this collection's entries with copies of another's. */
+    copy(other: Errors): this;
+    /**
+     * Return a new `Errors` collection with the same entries. Subsequent
+     * modifications on either side don't affect the other.
+     */
+    dup(): Errors;
+    /** Rich `ErrorObject` instances for each entry, in insertion order. */
+    get objects(): ErrorObject[];
+    /** First error (rich object) or `null`. */
+    get first(): ErrorObject | null;
+    /**
+     * Structured details payload. Each attribute maps to a list of
+     * `{ error: type, ...options }` records. Mirrors Rails' `errors.details`.
+     */
+    get details(): Record<string, Array<{
+        error: string | undefined;
+    } & Record<string, unknown>>>;
+    /** Group rich error objects by attribute. */
+    groupByAttribute(): Record<string, ErrorObject[]>;
+    /** Indifferent indexer — `errors.get('name')` is equivalent to `errors.on('name')`. */
+    get(attribute: string): string[];
+    /**
+     * Remove duplicate entries — same attribute + message + type. Mirrors
+     * Rails' `errors.uniq!`.
+     */
+    uniq(): this;
+    /** Import a foreign `ErrorEntry` or `ErrorObject`, optionally overriding attribute/type. */
+    import(error: ErrorEntry | ErrorObject, overrides?: {
+        attribute?: string;
+        type?: string;
+    }): ErrorEntry;
+    /**
+     * Indifferent indexer — returns `errors.on(attribute)` via a Proxy
+     * pseudo-property, supporting both `errors.byAttribute('name')` and
+     * the bracket-access shape `(errors as any)['name']`. Mirrors Rails'
+     * `errors[:name]` / `errors['name']`. (We can't do real bracket access
+     * without wrapping every Errors instance in a Proxy; this method-style
+     * accessor is the idiomatic TS equivalent.)
+     */
+    byAttribute(attribute: string): string[];
+    /**
+     * Rails-style `as_json`. With `{ fullMessages: true }`, each entry is
+     * the humanized "Attribute msg" form. Default returns the same shape
+     * as `messages`.
+     */
+    asJson(options?: {
+        fullMessages?: boolean;
+    }): Record<string, string[]>;
+    /**
+     * `to_hash(true)` returns full-message variant; otherwise plain messages.
+     * Convenience shim over `asJson({ fullMessages })`.
+     */
+    toHash(fullMessages?: boolean): Record<string, string[]>;
+    /**
+     * `of_kind?` — true when an entry exists whose attribute and type-or-
+     * message both match. Mirrors Rails' `errors.of_kind?(:name, :blank)`.
+     */
+    ofKind(attribute: string, typeOrMessage?: string): boolean;
+    /** Debug-friendly string representation. */
+    inspect(): string;
+    get count(): number;
+    get size(): number;
+    [Symbol.iterator](): IterableIterator<ErrorEntry>;
+    toJSON(): Record<string, string[]>;
+}
+
+/**
+ * Built-in validators. Each validator implements `validate(record, errors)`.
+ * Adapter-level validators (e.g. uniqueness) live in active-record.
+ */
+
+/**
+ * Optional context name passed to `Model#validate(context)`. Mirrors Rails'
+ * `valid?(:create)`/`valid?(:update)` — validators with `on` matching the
+ * context (or with no `on` at all) are evaluated; others are skipped.
+ */
+type ValidationContext = string;
+interface Validator<T = unknown> {
+    validate(record: T, errors: Errors, context?: ValidationContext): void | Promise<void>;
+}
+/** Common options shared across all validators. */
+type ValidatorOptions<T> = {
+    /**
+     * Custom error message. Can be a string or a function that receives
+     * `(record, data)` like Rails' Proc messages, where `data` is
+     * `{ attribute, value, type }`.
+     */
+    message?: string | ((record: T, data: {
+        attribute: string;
+        value: unknown;
+        type?: string;
+    }) => string);
+    if?: (record: T) => boolean;
+    unless?: (record: T) => boolean;
+    allowNull?: boolean;
+    allowBlank?: boolean;
+    /** Limit the validator to one or more validation contexts (e.g. `'create'`). */
+    on?: ValidationContext | ValidationContext[];
+    /** Skip the validator when the validation context matches one of these. */
+    exceptOn?: ValidationContext | ValidationContext[];
+    /**
+     * When set, validator failures throw immediately instead of accumulating
+     * in `record.errors`. Pass `true` for a generic `StrictValidationFailed`
+     * or a custom Error subclass to use that instead. Mirrors Rails'
+     * `validates(..., strict: true)`.
+     */
+    strict?: boolean | (new (message: string) => Error);
+};
+/** Thrown when a validator marked `strict: true` fails. */
+declare class StrictValidationFailed extends Error {
+    constructor(message: string);
+}
+declare class PresenceValidator<T> implements Validator<T> {
+    private readonly attribute;
+    private readonly options;
+    readonly kind = "presence";
+    readonly attributes: string[];
+    constructor(attribute: string, options?: ValidatorOptions<T>);
+    validate(record: T, errors: Errors, context?: ValidationContext): void;
+}
+declare class AbsenceValidator<T> implements Validator<T> {
+    private readonly attribute;
+    private readonly options;
+    readonly kind = "absence";
+    readonly attributes: string[];
+    constructor(attribute: string, options?: ValidatorOptions<T>);
+    validate(record: T, errors: Errors, context?: ValidationContext): void;
+}
+type LengthOptions<T> = ValidatorOptions<T> & {
+    minimum?: number;
+    maximum?: number;
+    is?: number;
+    in?: [number, number];
+    tooShort?: string;
+    tooLong?: string;
+    wrongLength?: string;
+};
+declare class LengthValidator<T> implements Validator<T> {
+    private readonly attribute;
+    private readonly options;
+    readonly kind = "length";
+    readonly attributes: string[];
+    constructor(attribute: string, options?: LengthOptions<T>);
+    validate(record: T, errors: Errors, context?: ValidationContext): void;
+}
+type FormatOptions<T> = ValidatorOptions<T> & {
+    with?: RegExp;
+    without?: RegExp;
+};
+declare class FormatValidator<T> implements Validator<T> {
+    private readonly attribute;
+    private readonly options;
+    readonly kind = "format";
+    readonly attributes: string[];
+    constructor(attribute: string, options: FormatOptions<T>);
+    validate(record: T, errors: Errors, context?: ValidationContext): void;
+}
+type InclusionOptions<T> = ValidatorOptions<T> & {
+    in: readonly unknown[];
+};
+declare class InclusionValidator<T> implements Validator<T> {
+    private readonly attribute;
+    private readonly options;
+    readonly kind = "inclusion";
+    readonly attributes: string[];
+    constructor(attribute: string, options: InclusionOptions<T>);
+    validate(record: T, errors: Errors, context?: ValidationContext): void;
+}
+type ExclusionOptions<T> = ValidatorOptions<T> & {
+    in: readonly unknown[];
+};
+declare class ExclusionValidator<T> implements Validator<T> {
+    private readonly attribute;
+    private readonly options;
+    readonly kind = "exclusion";
+    readonly attributes: string[];
+    constructor(attribute: string, options: ExclusionOptions<T>);
+    validate(record: T, errors: Errors, context?: ValidationContext): void;
+}
+type NumericalityOptions<T> = ValidatorOptions<T> & {
+    onlyInteger?: boolean;
+    greaterThan?: number;
+    greaterThanOrEqualTo?: number;
+    lessThan?: number;
+    lessThanOrEqualTo?: number;
+    equalTo?: number;
+    odd?: boolean;
+    even?: boolean;
+};
+declare class NumericalityValidator<T> implements Validator<T> {
+    private readonly attribute;
+    private readonly options;
+    readonly kind = "numericality";
+    readonly attributes: string[];
+    constructor(attribute: string, options?: NumericalityOptions<T>);
+    validate(record: T, errors: Errors, context?: ValidationContext): void;
+}
+type AcceptanceOptions<T> = ValidatorOptions<T> & {
+    accept?: readonly unknown[];
+};
+declare class AcceptanceValidator<T> implements Validator<T> {
+    private readonly attribute;
+    private readonly options;
+    readonly kind = "acceptance";
+    readonly attributes: string[];
+    constructor(attribute: string, options?: AcceptanceOptions<T>);
+    validate(record: T, errors: Errors, context?: ValidationContext): void;
+}
+type ConfirmationOptions<T> = ValidatorOptions<T> & {
+    caseSensitive?: boolean;
+};
+declare class ConfirmationValidator<T> implements Validator<T> {
+    private readonly attribute;
+    private readonly options;
+    readonly kind = "confirmation";
+    readonly attributes: string[];
+    constructor(attribute: string, options?: ConfirmationOptions<T>);
+    validate(record: T, errors: Errors, context?: ValidationContext): void;
+}
+
+/**
+ * `Model` is the active-model base — handles attribute storage, dirty
+ * tracking, validation, and callbacks. ActiveRecord's `Base` subclasses
+ * this to add persistence.
+ *
+ * Subclasses declare attributes with `static attribute(name, type)` or
+ * by populating the static `attributesSchema` (the AR layer does this
+ * automatically from `loadSchema`).
+ */
+
+/** A type reference accepted by `Model.attribute` — either a name or a Type instance. */
+type TypeRef = string | Type;
+/** Thrown by `Model#validateOrThrow` (mirrors Rails' `ActiveModel::ValidationError`). */
+declare class ValidationError extends Error {
+    record: Model;
+    constructor(record: Model);
+}
+declare class Model {
+    /** Per-instance attribute state, lazily initialized. */
+    protected _attributes: Attributes;
+    /** Per-instance error collection. */
+    readonly errors: Errors;
+    constructor(values?: Record<string, unknown>);
+    readAttribute(name: string): unknown;
+    writeAttribute(name: string, value: unknown): void;
+    /** Plain object snapshot. */
+    attributes(): Record<string, unknown>;
+    assignAttributes(values: Record<string, unknown>): this;
+    changed(): string[];
+    changes(): Record<string, [unknown, unknown]>;
+    attributeChanged(name: string): boolean;
+    attributeWas(name: string): unknown;
+    savedChanges(): Record<string, [unknown, unknown]>;
+    /**
+     * Tell the dirty tracker that `name` is about to be mutated in place,
+     * so subsequent reads detect it as a change. Mirrors Rails'
+     * `name_will_change!`.
+     */
+    willChange(name: string): void;
+    /**
+     * Revert pending changes. With no argument restores every changed
+     * attribute; with `names` restores only the listed ones. Mirrors
+     * Rails' `restore_attributes(['name'])`.
+     */
+    restoreAttributes(names?: string[]): void;
+    /** Reset both pending and last-saved changes — Rails' `clear_changes_information`. */
+    clearChangesInformation(): void;
+    validate(context?: ValidationContext): Promise<boolean>;
+    isValid(context?: ValidationContext): Promise<boolean>;
+    isInvalid(context?: ValidationContext): Promise<boolean>;
+    /** Mirrors Rails' `validate!`. Throws when invalid, returns true otherwise. */
+    validateOrThrow(context?: ValidationContext): Promise<boolean>;
+    toJSON(options?: {
+        except?: readonly string[];
+        only?: readonly string[];
+    }): Record<string, unknown>;
+    /**
+     * Return a new instance of the same class with the same attribute
+     * values. Mirrors Rails' `record.dup`. The AR layer overrides this
+     * to also clear the primary key so the duplicate looks like a fresh
+     * (unsaved) record.
+     */
+    dup(): this;
+    /** Register an attribute on this subclass. Returns the constructor for chaining. */
+    static attribute<This extends typeof Model>(this: This, name: string, type: TypeRef, options?: {
+        default?: unknown;
+    }): This;
+    /** Access the per-class `AttributeSet`. */
+    static attributesSchema<This extends typeof Model>(this: This): AttributeSet;
+    /** Register a validator instance. */
+    static validatesWith<This extends typeof Model>(this: This, validator: Validator<InstanceType<This>>): This;
+    /**
+     * Register a free-form block validator — `Klass.validate((record, errors) => ...)`.
+     * The function may be async and receives the same `(record, errors, context)`
+     * arguments every built-in validator does.
+     */
+    static validate<This extends typeof Model>(this: This, fn: (record: InstanceType<This>, errors: Errors, context?: ValidationContext) => void | Promise<void>, options?: ValidatorOptions<InstanceType<This>>): This;
+    /** All registered validators in declaration order (inherited + own). */
+    static validators<This extends typeof Model>(this: This): ReadonlyArray<Validator<InstanceType<This>>>;
+    /** Validators that target any of the given attribute names. */
+    static validatorsOn<This extends typeof Model>(this: This, ...attributes: string[]): ReadonlyArray<Validator<InstanceType<This>>>;
+    /** Reset all per-class validators. Rails' `clear_validators!`. */
+    static clearValidators<This extends typeof Model>(this: This): This;
+    /**
+     * Run a function once per attribute, accumulating errors. Mirrors Rails'
+     * `validates_each :a, :b do |record, attr, value| ... end`.
+     *
+     *   Klass.validatesEach(['a', 'b'], (record, attr, value, errors) => {
+     *     if (!ok(value)) errors.add(attr, 'bad');
+     *   });
+     */
+    static validatesEach<This extends typeof Model>(this: This, attributes: readonly string[], fn: (record: InstanceType<This>, attribute: string, value: unknown, errors: Errors) => void | Promise<void>, options?: ValidatorOptions<InstanceType<This>>): This;
+    /** Add a presence validator. */
+    static validatesPresenceOf<This extends typeof Model>(this: This, attribute: string, options?: ValidatorOptions<InstanceType<This>>): This;
+    static validatesAbsenceOf<This extends typeof Model>(this: This, attribute: string, options?: ValidatorOptions<InstanceType<This>>): This;
+    static validatesLengthOf<This extends typeof Model>(this: This, attribute: string, options: LengthOptions<InstanceType<This>>): This;
+    static validatesFormatOf<This extends typeof Model>(this: This, attribute: string, options: FormatOptions<InstanceType<This>>): This;
+    static validatesInclusionOf<This extends typeof Model>(this: This, attribute: string, options: InclusionOptions<InstanceType<This>>): This;
+    static validatesExclusionOf<This extends typeof Model>(this: This, attribute: string, options: ExclusionOptions<InstanceType<This>>): This;
+    static validatesNumericalityOf<This extends typeof Model>(this: This, attribute: string, options?: NumericalityOptions<InstanceType<This>>): This;
+    static validatesAcceptanceOf<This extends typeof Model>(this: This, attribute: string, options?: AcceptanceOptions<InstanceType<This>>): This;
+    static validatesConfirmationOf<This extends typeof Model>(this: This, attribute: string, options?: ConfirmationOptions<InstanceType<This>>): This;
+    /**
+     * Sugar mirroring Rails' `validates :name, presence: true, length: { minimum: 2 }`.
+     */
+    static validates<This extends typeof Model>(this: This, attribute: string, rules: {
+        presence?: boolean | ValidatorOptions<InstanceType<This>>;
+        absence?: boolean | ValidatorOptions<InstanceType<This>>;
+        length?: LengthOptions<InstanceType<This>>;
+        format?: FormatOptions<InstanceType<This>>;
+        inclusion?: InclusionOptions<InstanceType<This>>;
+        exclusion?: ExclusionOptions<InstanceType<This>>;
+        numericality?: boolean | NumericalityOptions<InstanceType<This>>;
+        acceptance?: boolean | AcceptanceOptions<InstanceType<This>>;
+        confirmation?: boolean | ConfirmationOptions<InstanceType<This>>;
+    }): This;
+    /** Options that can be passed to any callback registration helper. */
+    static setCallback<This extends typeof Model>(this: This, event: CallbackEvent, kind: CallbackKind, fn: CallbackFn<InstanceType<This>> | AroundCallbackFn<InstanceType<This>>, options?: {
+        if?: (record: InstanceType<This>) => boolean;
+        unless?: (record: InstanceType<This>) => boolean;
+        on?: string | string[];
+    }): This;
+    static beforeValidation<This extends typeof Model>(this: This, fn: CallbackFn<InstanceType<This>>, options?: {
+        on?: string | string[];
+        if?: (record: InstanceType<This>) => boolean;
+        unless?: (record: InstanceType<This>) => boolean;
+    }): This;
+    static afterValidation<This extends typeof Model>(this: This, fn: CallbackFn<InstanceType<This>>, options?: {
+        on?: string | string[];
+        if?: (record: InstanceType<This>) => boolean;
+        unless?: (record: InstanceType<This>) => boolean;
+    }): This;
+    static beforeSave<This extends typeof Model>(this: This, fn: CallbackFn<InstanceType<This>>): This;
+    static afterSave<This extends typeof Model>(this: This, fn: CallbackFn<InstanceType<This>>): This;
+    static aroundSave<This extends typeof Model>(this: This, fn: AroundCallbackFn<InstanceType<This>>): This;
+    static beforeCreate<This extends typeof Model>(this: This, ...fns: CallbackFn<InstanceType<This>>[]): This;
+    static afterCreate<This extends typeof Model>(this: This, ...fns: CallbackFn<InstanceType<This>>[]): This;
+    static beforeUpdate<This extends typeof Model>(this: This, fn: CallbackFn<InstanceType<This>>): This;
+    static afterUpdate<This extends typeof Model>(this: This, fn: CallbackFn<InstanceType<This>>): This;
+    static beforeDestroy<This extends typeof Model>(this: This, fn: CallbackFn<InstanceType<This>>): This;
+    static afterDestroy<This extends typeof Model>(this: This, fn: CallbackFn<InstanceType<This>>): This;
+    /**
+     * Run `fn` after the outermost transaction surrounding this record's
+     * save / destroy commits. When the record is touched outside a
+     * transaction, the callback fires immediately after the save.
+     */
+    static afterCommit<This extends typeof Model>(this: This, fn: CallbackFn<InstanceType<This>>, options?: {
+        on?: 'create' | 'update' | 'destroy' | Array<'create' | 'update' | 'destroy'>;
+    }): This;
+    /** Run `fn` when the surrounding transaction rolls back. */
+    static afterRollback<This extends typeof Model>(this: This, fn: CallbackFn<InstanceType<This>>, options?: {
+        on?: 'create' | 'update' | 'destroy' | Array<'create' | 'update' | 'destroy'>;
+    }): This;
+    /** Run `fn` whenever a new instance is constructed. */
+    static afterInitialize<This extends typeof Model>(this: This, fn: CallbackFn<InstanceType<This>>): This;
+    /** Run `fn` when a record is hydrated from the database. */
+    static afterFind<This extends typeof Model>(this: This, fn: CallbackFn<InstanceType<This>>): This;
+    /** Run `fn` after `touch()`. */
+    static afterTouch<This extends typeof Model>(this: This, fn: CallbackFn<InstanceType<This>>): This;
+    /** Run a registered callback chain — typically used by ActiveRecord persistence. */
+    static runCallbacks<This extends typeof Model>(this: This, event: CallbackEvent, record: InstanceType<This>, body: () => Promise<void | boolean>, context?: string): Promise<boolean>;
+}
+
+/**
+ * Tiny inflector — enough to convert class names into Rails-style table
+ * names (`User` -> `users`, `Person` -> `people`, `Octopus` -> `octopi`).
+ * Not a substitute for a full inflector (no `inflect.rb` here); add cases
+ * as needed.
+ */
+declare const pluralize: (word: string) => string;
+declare const underscore: (word: string) => string;
+declare const camelize: (word: string, lower?: boolean) => string;
+/** Convert a class name into a Rails-style table name (`UserAccount` -> `user_accounts`). */
+declare const tableize: (className: string) => string;
+
+/**
+ * `Name` — Rails-style `ActiveModel::Name`. Exposes singular/plural/
+ * element/collection/route_key/param_key/i18n_key/human/uncountable
+ * derivations for a class name. We compute these purely from the class
+ * name via the inflector — no i18n, no class introspection.
+ */
+declare class Name {
+    /** The class itself (or its name, when called with a class-name string). */
+    readonly klass: {
+        name: string;
+    };
+    /** The fully-qualified class name as written. */
+    readonly name: string;
+    /** Snake-case version of the (possibly namespaced) class name. e.g. `Post::TrackBack` -> `post_track_back`. */
+    readonly singular: string;
+    /** Plural form of `singular`. e.g. `post_track_back` -> `post_track_backs`. */
+    readonly plural: string;
+    /** Last segment, snake-cased. e.g. `Post::TrackBack` -> `track_back`. */
+    readonly element: string;
+    /** Forward-slash-joined collection name. e.g. `Post::TrackBack` -> `post/track_backs`. */
+    readonly collection: string;
+    /** Rails routing helper — plural element with optional namespace prefix. */
+    readonly route_key: string;
+    /** `singular` minus internal namespace separators. */
+    readonly param_key: string;
+    /** Slash-joined namespace key. e.g. `Post::TrackBack` -> `post/track_back`. */
+    readonly i18n_key: string;
+    /** Human-friendly element name. e.g. `track_back` -> `Track back`. */
+    readonly human: string;
+    /**
+     * Build a `Name` from a class (uses `klass.name`) or directly from a
+     * Ruby-style namespaced string ("Post::TrackBack").
+     */
+    constructor(klassOrName: string | {
+        name: string;
+    });
+    /** Whether the singular form is uncountable (plural === singular). */
+    get uncountable(): boolean;
+    toString(): string;
+}
+
+export { ABORT_SENTINEL, AbsenceValidator, type AcceptanceOptions, AcceptanceValidator, type AroundCallbackFn, type AttributeDefinition, AttributeSet, Attributes, BASE, BigIntType, BinaryType, BooleanType, CallbackChain, type CallbackEvent, type CallbackFn, type CallbackKind, type ConfirmationOptions, ConfirmationValidator, DateTimeType, DateType, DecimalType, type ErrorEntry, ErrorObject, Errors, type ExclusionOptions, ExclusionValidator, FloatType, type FormatOptions, FormatValidator, HaltError, type InclusionOptions, InclusionValidator, IntegerType, JSONType, type LengthOptions, LengthValidator, Model, Name, type NumericalityOptions, NumericalityValidator, PresenceValidator, StrictValidationFailed, StringType, type Type, type TypeRef, type ValidationContext, ValidationError, type Validator, type ValidatorOptions, ValueType, camelize, hasType, lookupType, pluralize, registerType, tableize, throwAbort, underscore, valuesEqual };