@orieljs/framework 0.1.0-alpha.5 → 0.1.0-alpha.7

package/docs/eloquent-mutators.md

@@ -0,0 +1,254 @@
+# Eloquent: mutators and casting
+
+Accessors, mutators and casts change attribute values as your models read and write them: a JSON column comes back as
+an object, a date as a `Date`, and a name in the case you chose.
+
+## Introduction
+
+A cast turns a column's stored value into the type your code works with, and back when the model is saved. An accessor
+is a method that computes an attribute when you read it, and a mutator one that sets it when you write it.
+
+## Accessors and mutators
+
+### Defining an accessor
+
+An accessor is a method named `get`, the attribute's name in StudlyCase, and `Attribute`. It receives the stored value,
+and returns what reading the attribute gives:
+
+```ts title="app/Models/User.ts"
+import { Model } from '@orieljs/framework'
+
+export class User extends Model {
+  /** Get the user's first name. */
+  getFirstNameAttribute(value: unknown): string {
+    const name = String(value ?? '')
+
+    return name.charAt(0).toUpperCase() + name.slice(1)
+  }
+}
+```
+
+`user.getAttribute('first_name')` then calls it, and so does reading `user.first_name`. `model:types` keeps the column's
+type for it; an accessor with no column, below, is typed from its return type.
+
+An accessor can also make an attribute that has no column, computed from others:
+
+```ts
+export class User extends Model {
+  getFullNameAttribute(): string {
+    return `${String(this.getAttribute('first_name'))} ${String(this.getAttribute('last_name'))}`
+  }
+}
+```
+
+To have it in the model's `toArray()` and JSON, add it to `appends` (see
+[Appending values to JSON](#appending-values-to-json)).
+
+### Defining a mutator
+
+A mutator is a method named `set`, the attribute's name in StudlyCase, and `Attribute`. It receives the value being
+set, and stores what it decides in `this.attributes`:
+
+```ts title="app/Models/User.ts"
+import { Model } from '@orieljs/framework'
+
+export class User extends Model {
+  /** Interact with the user's first name. */
+  setFirstNameAttribute(value: string): void {
+    this.attributes.first_name = value.toLowerCase()
+  }
+}
+```
+
+Every write goes through it: `user.first_name = 'Sally'`, `fill()`, `create()` and `update()`.
+
+> [!NOTE]
+> Laravel's accessors and mutators are methods returning an `Attribute` (`Attribute::make(get: …, set: …)`), or the
+> older `getXAttribute()` and `setXAttribute()` methods. Oriel has the older form.
+
+## Attribute casting
+
+`casts` maps attributes to the type they are read as:
+
+```ts title="app/Models/User.ts"
+import { Model, type CastDefinition } from '@orieljs/framework'
+
+export class User extends Model {
+  protected override casts: Readonly<Record<string, CastDefinition>> = {
+    is_admin: 'boolean',
+    options: 'json',
+    email_verified_at: 'datetime',
+  }
+}
+```
+
+A model with `model:types` types each attribute from its cast: `is_admin` as a `boolean`, `email_verified_at` as a
+`Date | null`.
+
+| Cast | Read as | Stored as |
+| --- | --- | --- |
+| `int`, `integer` | A number | The number |
+| `float`, `double`, `real` | A number | The number |
+| `string` | A string | The string |
+| `bool`, `boolean` | `true` or `false` | `1` or `0`, or a boolean on PostgreSQL |
+| `array`, `json`, `object` | The parsed JSON | JSON text |
+| `collection` | A [collection](collections.md) of the parsed JSON list | JSON text |
+| `date` | A `Date` at midnight UTC | `'2026-03-04'` |
+| `datetime` | A `Date` | `'2026-01-02 03:04:05'`, in UTC |
+| `immutable_date`, `immutable_datetime` | A `Date`, as `date` and `datetime` | The same |
+| `timestamp` | A Unix time in seconds | The date and time |
+| `decimal:2` | A string with that many decimals, `'9.50'` | The number |
+| `hashed` | The hash | A hash of the value, made when the model is saved |
+
+A built-in cast of `null` stays `null`; a custom cast's `get()` receives it. The incrementing key is always cast as an
+integer, and `created_at` and `updated_at` (and `deleted_at` with soft deletes) as datetimes.
+
+A cast string Oriel doesn't know, such as Laravel's `datetime:Y-m-d` with a format, throws an `InvalidCastError` when
+the attribute is read or written: "Call to undefined cast [datetime:Y-m-d] on column [launched_at] in model
+[Product].".
+
+### Array and JSON casting
+
+A `json` attribute is read as the parsed value. Changing it in place counts as a change, so `save()` writes it:
+
+```ts
+declare const user: User & { options: { theme: string } }
+// ---cut---
+user.options.theme = 'dark'
+
+await user.save()
+```
+
+### Date casting
+
+A date is stored in UTC, as `'2026-01-02 03:04:05'`, and read as a `Date`. In `toArray()` and JSON, dates are written
+as Laravel writes them: `'2026-01-02T03:04:05.000000Z'`.
+
+### Enum casting
+
+A TypeScript enum casts an attribute to its values:
+
+```ts title="app/Models/Server.ts"
+import { Model, type CastDefinition } from '@orieljs/framework'
+
+export enum ServerStatus {
+  Provisioned = 'provisioned',
+  Ready = 'ready',
+}
+
+export class Server extends Model {
+  protected override casts: Readonly<Record<string, CastDefinition>> = { status: ServerStatus }
+}
+```
+
+Setting a value that isn't one of the enum's throws: "\"nope\" is not a valid backing value for the cast of [status]
+on [Server].".
+
+### Hashed casting
+
+The `hashed` cast hashes a value when the model is saved, with your [hashing](hashing.md) driver, so you can set a
+plain password:
+
+```ts
+export class User extends Model {
+  protected override casts: Readonly<Record<string, CastDefinition>> = { password: 'hashed' }
+}
+```
+
+Until `save()`, reading the attribute gives what you set. A value that is already a hash made with your current
+settings is kept as it is; one made with other settings is refused.
+
+> [!NOTE]
+> Laravel hashes as soon as you set the attribute. Hashing is asynchronous in Oriel, so it happens in `save()`, before
+> the model's `saving` event, which sees the hash.
+
+### Query time casting
+
+`withCasts()` adds casts for one query, such as for a column a raw select adds:
+
+```ts
+const users = await User.query()
+  .select('users.*')
+  .selectRaw('(select max(created_at) from posts where posts.author_id = users.id) as last_posted_at')
+  .withCasts({ last_posted_at: 'datetime' })
+  .get()
+```
+
+> [!NOTE]
+> Laravel's encrypted casts, `AsArrayObject`, `AsCollection`, `AsStringable`, `AsEnumCollection` and castable value
+> objects aren't in Oriel; write a custom cast for them.
+
+## Custom casts
+
+A custom cast is a class with a `get()` method, which turns the stored value into what the model gives, and a `set()`
+method, which turns a value back into what is stored. `make:cast` writes one in `app/Casts`:
+
+```sh
+node oriel make:cast Money
+```
+
+```ts title="app/Casts/Money.ts"
+import type { CastsAttributes } from '@orieljs/framework'
+
+/** A price kept in cents, read in units: 1234 is 12.34. */
+export class Money implements CastsAttributes<number, number> {
+  get(_model: object, _key: string, value: unknown): number {
+    return Number(value) / 100
+  }
+
+  set(_model: object, _key: string, value: number): unknown {
+    return Math.round(value * 100)
+  }
+}
+```
+
+Name the class in `casts`, or give an instance:
+
+```ts title="app/Models/Product.ts"
+// @filename: app/Casts/Money.ts
+import type { CastsAttributes } from '@orieljs/framework'
+export declare class Money implements CastsAttributes<number, number> {
+  get(model: object, key: string, value: unknown): number
+  set(model: object, key: string, value: number): unknown
+}
+// ---cut---
+import { Model, type CastDefinition } from '@orieljs/framework'
+import { Money } from '../Casts/Money'
+
+export class Product extends Model {
+  protected override casts: Readonly<Record<string, CastDefinition>> = { price: Money }
+}
+```
+
+Both methods also receive the model, the attribute's name and all its stored attributes.
+
+## Serialization
+
+### Hiding attributes from JSON
+
+`hidden` lists the attributes left out of the model's `toArray()` and JSON, such as a password, and `visible` lists
+the only ones left in:
+
+```ts
+export class User extends Model {
+  protected override hidden = ['password', 'remember_token']
+}
+```
+
+`makeVisible()` and `makeHidden()` change the lists for one model: `user.makeVisible('password').toArray()`.
+
+### Appending values to JSON
+
+An accessor with no column isn't in `toArray()` and JSON unless you add it to `appends`:
+
+```ts
+export class User extends Model {
+  protected override appends = ['is_admin']
+
+  getIsAdminAttribute(): boolean {
+    return this.getAttribute('role') === 'admin'
+  }
+}
+```
+
+`append()` adds one for one model: `user.append('is_admin').toArray()`.

package/docs/eloquent-observers.md

@@ -0,0 +1,145 @@
+# Eloquent: observers
+
+Models dispatch events as they are created, updated, deleted and restored. Listen for them with a closure, or group
+the listeners for one model in an observer class.
+
+## Introduction
+
+A model dispatches these events, each with the model:
+
+| Event | When |
+| --- | --- |
+| `retrieved` | A model was read from the database |
+| `creating`, `created` | A new model is about to be saved for the first time, and was |
+| `updating`, `updated` | A model that exists is about to be saved with changes, and was |
+| `saving`, `saved` | A model is about to be saved, new or not, changed or not, and was |
+| `deleting`, `deleted` | A model is about to be deleted, or soft-deleted, and was |
+| `restoring`, `restored` | A soft-deleted model is about to be restored, and was |
+| `forceDeleting`, `forceDeleted` | A soft-deleted model is about to be deleted for good, and was |
+
+Creating a model dispatches `saving`, `creating`, `created`, then `saved`; updating one dispatches `saving`,
+`updating`, `updated`, then `saved`. Saving a model with no changes dispatches only `saving` and `saved`.
+
+A listener of a `-ing` event that returns `false` stops the operation: the model isn't saved, deleted or restored.
+
+> [!WARNING]
+> A query's `update()` and `delete()`, such as `Post.where('active', 0).delete()`, write the rows directly: no model
+> is read, and no event is dispatched.
+
+## Using closures
+
+Register a closure for an event in the model's static `booted()`, with the method named after the event:
+
+```ts title="app/Models/User.ts"
+import { Model } from '@orieljs/framework'
+
+export class User extends Model {
+  /** The "booted" method of the model. */
+  static override booted(): void {
+    this.created((user) => {
+      // ...
+    })
+  }
+}
+```
+
+`booted()` runs once, the first time the model is used in your app.
+
+## Observers
+
+### Defining observers
+
+An observer is a class whose methods are named after the events they handle. `make:observer` writes one in
+`app/Observers`, with `created()`, `updated()` and `deleted()` methods; give their parameter your model's type:
+
+```sh
+node oriel make:observer UserObserver
+```
+
+```ts title="app/Observers/UserObserver.ts"
+import type { User } from '../Models/User'
+
+export class UserObserver {
+  /** Handle the User "created" event. */
+  created(user: User): void {
+    // ...
+  }
+
+  /** Handle the User "updated" event. */
+  updated(user: User): void {
+    // ...
+  }
+
+  /** Handle the User "deleted" event. */
+  deleted(user: User): void {
+    // ...
+  }
+}
+```
+
+Register it with the model's `observe()`, in a service provider's `boot()`:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+// @filename: app/Observers/UserObserver.ts
+export declare class UserObserver {}
+// ---cut---
+import { ServiceProvider } from '@orieljs/framework'
+import { User } from '../Models/User'
+import { UserObserver } from '../Observers/UserObserver'
+
+export class AppServiceProvider extends ServiceProvider {
+  override boot(): void {
+    User.observe(UserObserver)
+  }
+}
+```
+
+Every method named after an event is registered. Oriel makes the observer through your app's container, so it can take
+a service with `inject()`; an instance works too: `User.observe(new UserObserver())`.
+
+A `-ing` method that returns `false` cancels the operation, as a closure does:
+
+```ts title="app/Observers/PostObserver.ts"
+import { Str } from '@orieljs/framework'
+import type { Post } from '../Models/Post'
+
+export class PostObserver {
+  /** Give a new post its slug. */
+  creating(post: Post): void {
+    post.slug = Str.slug(post.title)
+  }
+
+  /** A published post can't be deleted. */
+  deleting(post: Post): boolean {
+    return post.published_at === null
+  }
+}
+```
+
+> [!NOTE]
+> Laravel registers an observer with an attribute on the model (`#[ObservedBy]`), and can run its methods after the
+> transaction commits (`ShouldHandleEventsAfterCommit`). Oriel registers observers with `observe()`, and runs them as
+> the events happen. Laravel's `trashed` and `replicating` events aren't in Oriel.
+
+### Event names
+
+A model event is dispatched as `eloquent.<event>: <Model>`, such as `eloquent.created: User`, so you can also listen
+for it with `Event.listen()`. Laravel uses the model's full class name; Oriel uses the class's name.
+
+## Muting events
+
+`Model.withoutEvents()` runs a function with model events off, for the code it runs:
+
+```ts
+const user = await Model.withoutEvents(() => User.findOrFail(1))
+```
+
+`saveQuietly()` and `deleteQuietly()` save or delete one model without events:
+
+```ts
+const user = await User.findOrFail(1)
+
+user.name = 'Victoria Faith'
+
+await user.saveQuietly()
+```