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

package/src/Callbacks.ts

@@ -1,158 +0,0 @@
-/**
- * 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.
- */
-
-export type CallbackKind = 'before' | 'after' | 'around';
-export type CallbackEvent =
-  | 'validation'
-  | 'save'
-  | 'create'
-  | 'update'
-  | 'destroy'
-  | 'commit'
-  | 'rollback'
-  | 'initialize'
-  | 'find'
-  | 'touch';
-
-export type CallbackFn<T> = (record: T) => void | boolean | Promise<void | boolean>;
-export type AroundCallbackFn<T> = (record: T, run: () => Promise<void>) => Promise<void>;
-
-type CallbackEntry<T> = {
-  kind: CallbackKind;
-  fn: CallbackFn<T> | AroundCallbackFn<T>;
-  /** Conditional guard — if it returns false, the callback is skipped. */
-  if?: (record: T) => boolean;
-  unless?: (record: T) => boolean;
-  /** Limit the callback to one or more contexts (e.g. validation context). */
-  on?: string | string[];
-};
-
-/** Sentinel — throw inside a callback to cleanly halt the chain. */
-export class HaltError extends Error {
-  constructor() {
-    super('Callback chain halted');
-  }
-}
-
-/**
- * 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.
- */
-export const ABORT_SENTINEL = Symbol.for('@active-record-ts/active-model:abort');
-
-/** Convenience helper for chain implementations: convert "throw :abort" to a clean halt. */
-export const throwAbort = (): never => {
-  throw ABORT_SENTINEL;
-};
-
-export class CallbackChain<T> {
-  private readonly chains: Record<CallbackEvent, CallbackEntry<T>[]> = {
-    validation: [],
-    save: [],
-    create: [],
-    update: [],
-    destroy: [],
-    commit: [],
-    rollback: [],
-    initialize: [],
-    find: [],
-    touch: [],
-  };
-
-  /** 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 {
-    this.chains[event].push({ kind, fn, if: options?.if, unless: options?.unless, on: options?.on });
-  }
-
-  /** Copy chains from a parent so subclasses inherit before extending. */
-  inheritFrom(parent: CallbackChain<T>): void {
-    for (const event of Object.keys(this.chains) as CallbackEvent[]) {
-      this.chains[event] = [...parent.chains[event]];
-    }
-  }
-
-  /**
-   * 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.
-   */
-  async run(event: CallbackEvent, record: T, body: () => Promise<void | boolean>, context?: string): Promise<boolean> {
-    const entries = this.chains[event];
-    const befores = entries.filter((e) => e.kind === 'before');
-    const afters = entries.filter((e) => e.kind === 'after');
-    const arounds = entries.filter((e) => e.kind === 'around');
-
-    for (const entry of befores) {
-      if (!guard(entry, record, context)) continue;
-      try {
-        const result = await (entry.fn as CallbackFn<T>)(record);
-        if (result === false) return false;
-      } catch (err) {
-        if (err instanceof HaltError) return false;
-        if (err === ABORT_SENTINEL) return false;
-        throw err;
-      }
-    }
-
-    // Build the inner runner as a chain of around callbacks wrapping `body`.
-    // Capture body's return value so after-callbacks can be skipped when it
-    // returns false (mirrors Rails' "after callbacks skipped when block
-    // returns false" behavior). When there are no around callbacks, we
-    // skip the wrapper to keep the microtask cost identical to a bare
-    // `await body()` — some callers (after_initialize) rely on that.
-    let bodyHalted = false;
-    if (arounds.length === 0) {
-      const r = await body();
-      if (r === false) bodyHalted = true;
-    } else {
-      const bodyRunner = async (): Promise<void> => {
-        const r = await body();
-        if (r === false) bodyHalted = true;
-      };
-      let runner: () => Promise<void> = bodyRunner;
-      for (let i = arounds.length - 1; i >= 0; i--) {
-        const around = arounds[i];
-        if (!around || !guard(around, record, context)) continue;
-        const inner = runner;
-        runner = () => (around.fn as AroundCallbackFn<T>)(record, inner);
-      }
-      await runner();
-    }
-
-    if (bodyHalted) return false;
-
-    for (const entry of afters) {
-      if (!guard(entry, record, context)) continue;
-      try {
-        await (entry.fn as CallbackFn<T>)(record);
-      } catch (err) {
-        if (err instanceof HaltError) break;
-        if (err === ABORT_SENTINEL) break;
-        throw err;
-      }
-    }
-    return true;
-  }
-}
-
-const guard = <T>(entry: CallbackEntry<T>, record: T, context?: string): boolean => {
-  if (entry.on !== undefined) {
-    const wanted = Array.isArray(entry.on) ? entry.on : [entry.on];
-    if (context === undefined) return false;
-    if (!wanted.includes(context)) return false;
-  }
-  if (entry.if && !entry.if(record)) return false;
-  if (entry.unless && entry.unless(record)) return false;
-  return true;
-};

package/src/Errors.ts

@@ -1,398 +0,0 @@
-/**
- * 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)`.
- */
-
-export 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.
- */
-export class ErrorObject {
-  constructor(private readonly entry: ErrorEntry) {}
-  get attribute(): string { return this.entry.attribute; }
-  get message(): string { return this.entry.message; }
-  get type(): string | undefined { return this.entry.type; }
-  get options(): Record<string, unknown> | undefined { return this.entry.options; }
-  fullMessage(): string {
-    return this.entry.attribute === BASE ? this.entry.message : `${humanize(this.entry.attribute)} ${this.entry.message}`;
-  }
-  /** Internal accessor for `Errors#import` — returns the wrapped entry. */
-  toEntry(): ErrorEntry {
-    return this.entry;
-  }
-}
-
-/** Special attribute name for errors that aren't tied to a specific column. */
-export const BASE = 'base';
-
-/**
- * Default messages for known error types. Mirrors a small subset of
- * Rails' `errors.messages.*` locale entries — enough to keep tests
- * green without pulling in a full i18n backend. Format strings expand
- * `%{key}` against the options hash at lookup time.
- */
-const DEFAULT_MESSAGES: Record<string, string> = {
-  invalid: 'is invalid',
-  blank: "can't be blank",
-  present: 'must be blank',
-  too_short: 'is too short (minimum is %{count} characters)',
-  too_long: 'is too long (maximum is %{count} characters)',
-  wrong_length: 'is the wrong length (should be %{count} characters)',
-  taken: 'has already been taken',
-  not_a_number: 'is not a number',
-  greater_than: 'must be greater than %{count}',
-  greater_than_or_equal_to: 'must be greater than or equal to %{count}',
-  less_than: 'must be less than %{count}',
-  less_than_or_equal_to: 'must be less than or equal to %{count}',
-  equal_to: 'must be equal to %{count}',
-  odd: 'must be odd',
-  even: 'must be even',
-  inclusion: 'is not included in the list',
-  exclusion: 'is reserved',
-  accepted: 'must be accepted',
-  confirmation: "doesn't match %{attribute}",
-  empty: "can't be empty",
-};
-
-const isKnownType = (value: string): boolean => Object.prototype.hasOwnProperty.call(DEFAULT_MESSAGES, value);
-
-const interpolate = (template: string, options: Record<string, unknown> = {}): string =>
-  template.replace(/%\{(\w+)\}/g, (_, key) => (key in options ? String(options[key]) : `%{${key}}`));
-
-export type AddOptions = {
-  type?: string;
-  options?: Record<string, unknown>;
-};
-
-export class Errors {
-  private readonly entries: ErrorEntry[] = [];
-
-  /**
-   * 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 = 'invalid', options: AddOptions & Record<string, unknown> = {}): ErrorEntry {
-    const { type: explicitType, options: explicitOptions, message: explicitMessage, ...payload } = options as {
-      type?: string;
-      options?: Record<string, unknown>;
-      message?: string;
-    };
-    const mergedOptions = { ...payload, ...(explicitOptions ?? {}) };
-    let type: string | undefined;
-    let message: string;
-    if (explicitType) {
-      type = explicitType;
-      message = explicitMessage ?? (isKnownType(messageOrType) ? interpolate(DEFAULT_MESSAGES[messageOrType]!, mergedOptions) : messageOrType);
-    } else if (isKnownType(messageOrType)) {
-      type = messageOrType;
-      message = explicitMessage ?? interpolate(DEFAULT_MESSAGES[messageOrType]!, mergedOptions);
-    } else {
-      message = explicitMessage ?? messageOrType;
-    }
-    const entry: ErrorEntry = {
-      attribute,
-      message,
-      ...(type !== undefined ? { type } : {}),
-      ...(Object.keys(mergedOptions).length > 0 ? { options: mergedOptions } : {}),
-    };
-    this.entries.push(entry);
-    return entry;
-  }
-
-  /** True when there are no errors at all. */
-  get empty(): boolean {
-    return this.entries.length === 0;
-  }
-  /** True when at least one error has been recorded. */
-  get any(): boolean {
-    return this.entries.length > 0;
-  }
-
-  clear(): void {
-    this.entries.length = 0;
-  }
-  delete(attribute: string, type?: string, matchOptions?: Record<string, unknown>): string[] {
-    const deleted: string[] = [];
-    for (let i = this.entries.length - 1; i >= 0; i--) {
-      const e = this.entries[i]!;
-      if (e.attribute !== attribute) continue;
-      if (type !== undefined && e.type !== type) continue;
-      if (matchOptions && !matchesOptions(e.options, matchOptions)) continue;
-      deleted.unshift(e.message);
-      this.entries.splice(i, 1);
-    }
-    return deleted;
-  }
-
-  on(attribute: string): string[] {
-    return this.entries.filter((e) => e.attribute === attribute).map((e) => e.message);
-  }
-  includes(attribute: string): boolean {
-    return this.entries.some((e) => e.attribute === attribute);
-  }
-
-  /** All `[attribute, message]` pairs, in insertion order. */
-  get messages(): Record<string, string[]> {
-    const out: Record<string, string[]> = {};
-    for (const entry of this.entries) {
-      (out[entry.attribute] ??= []).push(entry.message);
-    }
-    return out;
-  }
-
-  /** Distinct attributes that currently carry at least one error. */
-  get attributeNames(): string[] {
-    const seen = new Set<string>();
-    const ordered: string[] = [];
-    for (const entry of this.entries) {
-      if (!seen.has(entry.attribute)) {
-        seen.add(entry.attribute);
-        ordered.push(entry.attribute);
-      }
-    }
-    return ordered;
-  }
-
-  /** Predicate: was an error matching the given attribute (and optional type / options) added? */
-  added(attribute: string, type?: string, matchOptions?: Record<string, unknown>): boolean {
-    return this.entries.some((e) => {
-      if (e.attribute !== attribute) return false;
-      if (type !== undefined && e.type !== type) return false;
-      if (matchOptions && !matchesOptions(e.options, matchOptions)) return false;
-      return true;
-    });
-  }
-
-  /** Filter entries by attribute / type / options. */
-  where(attribute: string, type?: string, matchOptions?: Record<string, unknown>): ErrorEntry[] {
-    return this.entries.filter((e) => {
-      if (e.attribute !== attribute) return false;
-      if (type !== undefined && e.type !== type) return false;
-      if (matchOptions && !matchesOptions(e.options, matchOptions)) return false;
-      return true;
-    });
-  }
-
-  /** Messages for a specific attribute, optionally filtered by type. */
-  messagesFor(attribute: string, type?: string): string[] {
-    return this.where(attribute, type).map((e) => e.message);
-  }
-
-  /** Human-readable strings like `"Name can't be blank"`. */
-  get fullMessages(): string[] {
-    return this.entries.map((e) => (e.attribute === BASE ? e.message : `${humanize(e.attribute)} ${e.message}`));
-  }
-
-  fullMessagesFor(attribute: string, type?: string): string[] {
-    return this.where(attribute, type).map((e) => (attribute === BASE ? e.message : `${humanize(attribute)} ${e.message}`));
-  }
-
-  /** Standalone full-message formatter (no entries side effect). */
-  fullMessage(attribute: string, message: string): string {
-    return attribute === BASE ? message : `${humanize(attribute)} ${message}`;
-  }
-
-  /** Append every entry from `other` to this collection. */
-  merge(other: Errors): this {
-    if (other === this) return this;
-    for (const entry of other.entries) this.entries.push({ ...entry, options: entry.options ? { ...entry.options } : undefined });
-    return this;
-  }
-
-  /** Replace this collection's entries with copies of another's. */
-  copy(other: Errors): this {
-    this.clear();
-    return this.merge(other);
-  }
-
-  /**
-   * Return a new `Errors` collection with the same entries. Subsequent
-   * modifications on either side don't affect the other.
-   */
-  dup(): Errors {
-    const copy = new Errors();
-    copy.merge(this);
-    return copy;
-  }
-
-  /** Rich `ErrorObject` instances for each entry, in insertion order. */
-  get objects(): ErrorObject[] {
-    return this.entries.map((e) => new ErrorObject(e));
-  }
-
-  /** First error (rich object) or `null`. */
-  get first(): ErrorObject | null {
-    return this.entries[0] ? new ErrorObject(this.entries[0]) : 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>>> {
-    const out: Record<string, Array<{ error: string | undefined } & Record<string, unknown>>> = {};
-    for (const entry of this.entries) {
-      (out[entry.attribute] ??= []).push({ error: entry.type, ...(entry.options ?? {}) });
-    }
-    return out;
-  }
-
-  /** Group rich error objects by attribute. */
-  groupByAttribute(): Record<string, ErrorObject[]> {
-    const out: Record<string, ErrorObject[]> = {};
-    for (const entry of this.entries) {
-      (out[entry.attribute] ??= []).push(new ErrorObject(entry));
-    }
-    return out;
-  }
-
-  /** Indifferent indexer — `errors.get('name')` is equivalent to `errors.on('name')`. */
-  get(attribute: string): string[] {
-    return this.on(attribute);
-  }
-
-  /**
-   * Remove duplicate entries — same attribute + message + type. Mirrors
-   * Rails' `errors.uniq!`.
-   */
-  uniq(): this {
-    const seen = new Set<string>();
-    for (let i = this.entries.length - 1; i >= 0; i--) {
-      const e = this.entries[i]!;
-      const key = `${e.attribute}${e.message}${e.type ?? ''}`;
-      if (seen.has(key)) this.entries.splice(i, 1);
-      else seen.add(key);
-    }
-    return this;
-  }
-
-  /** Import a foreign `ErrorEntry` or `ErrorObject`, optionally overriding attribute/type. */
-  import(
-    error: ErrorEntry | ErrorObject,
-    overrides: { attribute?: string; type?: string } = {},
-  ): ErrorEntry {
-    const base: ErrorEntry = error instanceof ErrorObject ? error.toEntry() : error;
-    const next: ErrorEntry = {
-      attribute: overrides.attribute ?? base.attribute,
-      message: base.message,
-      type: overrides.type ?? base.type,
-      options: base.options ? { ...base.options } : undefined,
-    };
-    this.entries.push(next);
-    return next;
-  }
-
-  /**
-   * 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[] {
-    return this.on(attribute);
-  }
-
-  /**
-   * 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[]> {
-    if (!options.fullMessages) return this.messages;
-    const out: Record<string, string[]> = {};
-    for (const entry of this.entries) {
-      const full = entry.attribute === BASE ? entry.message : `${humanize(entry.attribute)} ${entry.message}`;
-      (out[entry.attribute] ??= []).push(full);
-    }
-    return out;
-  }
-
-  /**
-   * `to_hash(true)` returns full-message variant; otherwise plain messages.
-   * Convenience shim over `asJson({ fullMessages })`.
-   */
-  toHash(fullMessages = false): Record<string, string[]> {
-    return this.asJson({ fullMessages });
-  }
-
-  /**
-   * `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 {
-    if (typeOrMessage === undefined) return this.includes(attribute);
-    return this.entries.some((e) => {
-      if (e.attribute !== attribute) return false;
-      // Match either the type discriminator or the literal message.
-      return e.type === typeOrMessage || e.message === typeOrMessage;
-    });
-  }
-
-  /** Debug-friendly string representation. */
-  inspect(): string {
-    const parts = this.entries.map((e) => `#<Error attribute=${e.attribute}, message=${JSON.stringify(e.message)}>`);
-    return `#<Errors:[${parts.join(', ')}]>`;
-  }
-
-  get count(): number {
-    return this.entries.length;
-  }
-  get size(): number {
-    return this.entries.length;
-  }
-
-  [Symbol.iterator](): IterableIterator<ErrorEntry> {
-    return this.entries[Symbol.iterator]();
-  }
-
-  toJSON(): Record<string, string[]> {
-    return this.messages;
-  }
-}
-
-/** Two options hashes match when every key in `expected` has the same value in `actual`. */
-const matchesOptions = (actual: Record<string, unknown> | undefined, expected: Record<string, unknown>): boolean => {
-  if (!actual) return Object.keys(expected).length === 0;
-  for (const [k, v] of Object.entries(expected)) {
-    if (actual[k] !== v) return false;
-  }
-  return true;
-};
-
-/** Rails-style humanize: split camelCase / snake_case, lower-case everything, then upcase only the first letter. */
-const humanize = (attribute: string): string => {
-  // Dotted attribute names like `replies.name` (nested attributes) collapse
-  // to a single phrase: dots become underscores, then snake/camel split.
-  // Matches `String#humanize` in Rails.
-  const flattened = attribute.replace(/\./g, '_');
-  const spaced = flattened.replace(/[_-]+/g, ' ').replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase();
-  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
-};