@active-record-ts/active-model 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Stathis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# `@active-record-ts/active-model`
+
+Typed attributes, dirty tracking, validations, and callbacks for plain TypeScript classes — no database. A port of Rails' [`ActiveModel`](https://github.com/rails/rails/tree/main/activemodel).
+
+Used by [`@active-record-ts/active-record`](../active-record) for persistence; usable on its own for form objects, API payloads, etc.
+
+## Usage
+
+```ts
+import { Model } from '@active-record-ts/active-model';
+
+class Signup extends Model {
+  declare email: string;
+  declare age: number;
+}
+
+Signup.attribute('email', 'string');
+Signup.attribute('age', 'integer');
+Signup.validates('email', { presence: true, format: { with: /@/ } });
+Signup.validates('age', { numericality: { greaterThanOrEqualTo: 13 } });
+
+const s = new Signup({ email: 'a@b.c', age: 12 });
+await s.validate();          // false
+s.errors.fullMessages;       // ["Age must be greater than or equal to 13"]
+```
+
+## Features
+
+- **Typed attributes** — `attribute(name, type)`. Built-ins: `string`, `integer`, `bigint`, `float`, `decimal`, `boolean`, `date`, `datetime`, `binary`, `json`. Register your own with `registerType`.
+- **Dirty tracking** — `record.changed()`, `record.changes()`, `record.wasChanged(attr)`, `record.savedChanges()`.
+- **Validations** — `presence`, `absence`, `format`, `length`, `numericality`, `inclusion`, `exclusion`, `acceptance`, `confirmation`.
+- **Callbacks** — `beforeValidation`, `afterValidation`, `beforeSave`, `afterSave`, `aroundSave`. Throw `HaltError` (or call `throwAbort()`) inside a `before*` callback to halt the chain.
+- **Errors** — `record.errors` exposes Rails-style `add`, `on`, `fullMessages`, etc.
+- **Inflector** — `camelize`, `underscore`, `pluralize`, `tableize`.
+
+## Test
+
+```bash
+bun run test:active-model
+```

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@active-record-ts/active-model",
+  "version": "1.0.0",
+  "description": "Rails-style ActiveModel for TypeScript — typed attributes, dirty tracking, validations, callbacks.",
+  "author": "Alexander Stathis <stathis.alexanderj@gmail.com> (github.com/stathis-alexander)",
+  "license": "MIT",
+  "type": "module",
+  "module": "src/index.ts",
+  "files": ["src", "README.md", "LICENSE"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stathis-alexander/active-record-ts.git",
+    "directory": "packages/active-model"
+  },
+  "bugs": "https://github.com/stathis-alexander/active-record-ts/issues",
+  "homepage": "https://github.com/stathis-alexander/active-record-ts/tree/main/packages/active-model#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bun tsc --noEmit"
+  }
+}

package/src/AttributeSet.ts

@@ -0,0 +1,221 @@
+/**
+ * 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)
+ */
+
+import { type Type, valuesEqual } from './Type';
+
+/** Declaration of a single attribute on a model. */
+export type AttributeDefinition = {
+  name: string;
+  type: Type;
+  /** Default applied when a record is new and the attribute is not assigned. */
+  default?: unknown;
+};
+
+export class AttributeSet {
+  private readonly definitions = new Map<string, AttributeDefinition>();
+  /** Insertion-ordered list of attribute names, for stable iteration. */
+  private readonly names: string[] = [];
+
+  /** Register an attribute (or replace an existing one). */
+  define(definition: AttributeDefinition): void {
+    if (!this.definitions.has(definition.name)) this.names.push(definition.name);
+    this.definitions.set(definition.name, definition);
+  }
+
+  has(name: string): boolean {
+    return this.definitions.has(name);
+  }
+  get(name: string): AttributeDefinition | undefined {
+    return this.definitions.get(name);
+  }
+  keys(): string[] {
+    return this.names.slice();
+  }
+  /** Stable iteration of definitions in declaration order. */
+  *[Symbol.iterator](): IterableIterator<AttributeDefinition> {
+    for (const name of this.names) yield this.definitions.get(name)!;
+  }
+  size(): number {
+    return this.definitions.size;
+  }
+  clone(): AttributeSet {
+    const copy = new AttributeSet();
+    for (const def of this) copy.define(def);
+    return copy;
+  }
+}
+
+/** Per-instance attribute state — values + originals + last-save snapshot. */
+export class Attributes {
+  private readonly current = new Map<string, unknown>();
+  private readonly original = new Map<string, unknown>();
+  private previousChanges: Map<string, [unknown, unknown]> = new Map();
+  private readonly accessedNames = new Set<string>();
+
+  constructor(private readonly set: AttributeSet) {}
+
+  /** Hydrate attributes after loading from the DB. Skips dirty tracking. */
+  hydrate(raw: Record<string, unknown>): void {
+    for (const def of this.set) {
+      const incoming = raw[def.name];
+      const value = def.type.deserialize(incoming);
+      this.current.set(def.name, value);
+      this.original.set(def.name, value);
+    }
+  }
+
+  /** Hydrate attributes for a brand-new record (applies defaults). */
+  hydrateDefaults(overrides: Record<string, unknown> = {}): void {
+    for (const def of this.set) {
+      const provided = def.name in overrides;
+      const raw = provided ? overrides[def.name] : def.default;
+      const value = def.type.cast(raw);
+      this.current.set(def.name, value);
+      this.original.set(def.name, value);
+    }
+  }
+
+  /** Read an attribute by name, returning the canonical (cast) value. */
+  read(name: string): unknown {
+    this.accessedNames.add(name);
+    return this.current.get(name);
+  }
+
+  /** Names that have been read since hydration. Mirrors Rails' `accessed_attributes`. */
+  accessed(): string[] {
+    return [...this.accessedNames].filter((n) => this.set.has(n));
+  }
+
+  /** Write an attribute by name. Type-casts before storing. */
+  write(name: string, value: unknown): void {
+    const def = this.set.get(name);
+    if (!def) {
+      this.current.set(name, value);
+      return;
+    }
+    this.current.set(name, def.type.cast(value));
+  }
+
+  /**
+   * 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 {
+    if (!this.current.has(name) && !this.original.has(name)) return;
+    // The next read sees the current value as "the new value"; rewind
+    // original to a snapshot taken BEFORE further mutation.
+    const value = this.current.get(name);
+    // Stash a deep-ish copy of the current value as the original so subsequent
+    // in-place mutation to `current` is detectable as a change.
+    const snapshot = typeof value === 'object' && value !== null
+      ? (Array.isArray(value) ? [...value] : { ...value })
+      : value;
+    this.original.set(name, snapshot);
+  }
+
+  /** Was this attribute changed since the last commit? */
+  changed(name: string): boolean {
+    if (!this.current.has(name)) return false;
+    const def = this.set.get(name);
+    const original = this.original.get(name);
+    const value = this.current.get(name);
+    if (!def) return original !== value;
+    return !valuesEqual(def.type, original as never, value as never);
+  }
+
+  /** List of attribute names that differ from their originals. */
+  changedAttributes(): string[] {
+    const result: string[] = [];
+    for (const name of this.set.keys()) {
+      if (this.changed(name)) result.push(name);
+    }
+    return result;
+  }
+
+  /** `{ name: [from, to] }` for every changed attribute. */
+  changes(): Record<string, [unknown, unknown]> {
+    const out: Record<string, [unknown, unknown]> = {};
+    for (const name of this.changedAttributes()) {
+      out[name] = [this.original.get(name), this.current.get(name)];
+    }
+    return out;
+  }
+
+  /** Original value of `name` (current value if unchanged). */
+  was(name: string): unknown {
+    return this.original.get(name);
+  }
+
+  /** Snapshot for SAVE — return the canonical values for each attribute. */
+  toHash(): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    for (const name of this.set.keys()) out[name] = this.current.get(name);
+    return out;
+  }
+
+  /** Snapshot of only the dirty attributes (for UPDATE statements). */
+  dirtyHash(): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    for (const name of this.changedAttributes()) out[name] = this.current.get(name);
+    return out;
+  }
+
+  /** Serialized snapshot of all attributes (driver-ready values). */
+  serializedHash(): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    for (const def of this.set) {
+      out[def.name] = def.type.serialize(this.current.get(def.name) as never);
+    }
+    return out;
+  }
+
+  /** Mark the current values as the new baseline. Captures previous changes. */
+  commit(): void {
+    const previous = new Map<string, [unknown, unknown]>();
+    for (const name of this.changedAttributes()) {
+      previous.set(name, [this.original.get(name), this.current.get(name)]);
+      this.original.set(name, this.current.get(name));
+    }
+    this.previousChanges = previous;
+  }
+
+  /** Drop all pending and recorded changes — used by `clearChangesInformation`. */
+  clearChanges(): void {
+    for (const [name, value] of this.current) this.original.set(name, value);
+    this.previousChanges = new Map();
+  }
+
+  /** Revert all pending changes. */
+  restore(): void {
+    for (const name of this.changedAttributes()) {
+      this.current.set(name, this.original.get(name));
+    }
+  }
+
+  /** Changes that were applied during the last `commit`. */
+  savedChanges(): Record<string, [unknown, unknown]> {
+    const out: Record<string, [unknown, unknown]> = {};
+    for (const [name, pair] of this.previousChanges) out[name] = pair;
+    return out;
+  }
+
+  attributeSet(): AttributeSet {
+    return this.set;
+  }
+}

package/src/Callbacks.ts

@@ -0,0 +1,158 @@
+/**
+ * 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;
+};