@shaferllc/keel 0.80.0 → 0.81.0

package/docs/examples/accounts.ts

@@ -0,0 +1,150 @@
+// Typechecked example for docs/accounts.md.
+import { Application } from "@shaferllc/keel/core";
+import {
+  AccountsServiceProvider,
+  attempt,
+  completeTwoFactor,
+  confirmTwoFactor,
+  disableTwoFactor,
+  enableTwoFactor,
+  hasTwoFactor,
+  regenerateRecoveryCodes,
+  requestPasswordReset,
+  resetPassword,
+  sendVerificationEmail,
+  verifyEmail,
+  accountStore,
+  setAccountStore,
+  type AccountUser,
+} from "@shaferllc/keel/accounts";
+
+const app = new Application();
+
+/* ------------------------------- turning it on ---------------------------- */
+
+app.register(AccountsServiceProvider);
+
+/* ---------------------------------- login --------------------------------- */
+
+async function login(email: string, password: string) {
+  const result = await attempt(email, password);
+
+  if (result.status === "failed") {
+    return { error: "Those credentials don't match." };
+  }
+
+  if (result.status === "two-factor") {
+    // Nothing is logged in yet. Hold the challenge, ask for a code.
+    return { twoFactor: true, challenge: result.challenge };
+  }
+
+  return { user: result.user };
+}
+
+async function finishTwoFactor(challenge: string, code: string) {
+  // Takes an authenticator code or a recovery code.
+  const user = await completeTwoFactor(challenge, code);
+  if (!user) return { error: "That code isn't valid." };
+
+  return { user };
+}
+
+/* ------------------------------ password reset ---------------------------- */
+
+async function forgot(email: string) {
+  await requestPasswordReset(email);
+  // Always the same answer, whether or not that address has an account.
+  return { status: "If that address has an account, a link is on its way." };
+}
+
+async function reset(token: string, password: string) {
+  const ok = await resetPassword(token, password);
+  return ok ? { status: "Password reset." } : { error: "That link is invalid or expired." };
+}
+
+/* --------------------------- email verification --------------------------- */
+
+async function afterRegistration(user: AccountUser) {
+  await sendVerificationEmail(user);
+}
+
+async function confirmEmail(token: string) {
+  const user = await verifyEmail(token);
+  return user ? { status: "Confirmed." } : { error: "That link is invalid or expired." };
+}
+
+/* -------------------------------- two factor ------------------------------ */
+
+async function startTwoFactor(user: AccountUser) {
+  // Step one: a secret and recovery codes — but 2FA is NOT on yet.
+  const setup = await enableTwoFactor(user, { issuer: "Acme" });
+
+  // Render setup.uri to a QR code locally. It contains the secret; never send it
+  // to a third-party QR service.
+  return {
+    uri: setup.uri,
+    secret: setup.secret,
+    recoveryCodes: setup.recoveryCodes, // shown once
+  };
+}
+
+async function finishSetup(user: AccountUser, code: string) {
+  // Step two: a working code turns it on. Without this, a bad scan locks them out.
+  const ok = await confirmTwoFactor(user, code);
+  return ok ? { status: "Two-factor is on." } : { error: "That code isn't valid." };
+}
+
+async function accountSettings(user: AccountUser) {
+  return {
+    twoFactorEnabled: hasTwoFactor(user),
+  };
+}
+
+async function newCodes(user: AccountUser) {
+  return regenerateRecoveryCodes(user); // invalidates the old set
+}
+
+async function turnOff(user: AccountUser) {
+  await disableTwoFactor(user);
+}
+
+/* ------------------------------ a custom store ---------------------------- */
+
+// Users somewhere other than a `users` table? Replace the whole store. (Anything
+// that can find a user and update one will do — here, a map.)
+const people = new Map<string | number, AccountUser>();
+
+setAccountStore({
+  async findById(id) {
+    return people.get(id) ?? null;
+  },
+  async findByEmail(email) {
+    for (const person of people.values()) {
+      if (person.email === email.toLowerCase()) return person;
+    }
+    return null;
+  },
+  async update(id, values) {
+    const person = people.get(id);
+    if (person) people.set(id, { ...person, ...values });
+  },
+});
+
+// The store the rest of the module reads through.
+const store = accountStore();
+
+export {
+  login,
+  finishTwoFactor,
+  forgot,
+  reset,
+  afterRegistration,
+  confirmEmail,
+  startTwoFactor,
+  finishSetup,
+  accountSettings,
+  newCodes,
+  turnOff,
+  app,
+  store,
+};

package/docs/migrations.md

@@ -73,12 +73,41 @@ t.boolean("active").default(true);     // sqlite: DEFAULT 1, else DEFAULT true
 t.integer("retries").default(0);       // ... DEFAULT 0
 ```
 
-For anything the builder doesn't cover — indexes, foreign keys, an `ALTER
-TABLE` — `schema.raw(sql, bindings?)` runs arbitrary SQL:
+### Indexes and foreign keys
+
+`createTable` builds indexes and foreign keys alongside the columns:
+
+```ts
+schema.createTable("members", (t) => {
+  t.id();
+  t.integer("team_id");
+  t.string("email");
+  t.uniqueIndex("email");                       // or t.index(["a", "b"]) for composite
+  t.foreign("team_id").references("id").on("teams").onDelete("cascade");
+});
+```
+
+### Altering a table
+
+`schema.alterTable(name, build)` adds, renames, and drops columns and indexes on
+an existing table (dialect-aware SQL). Drop an index before the column it covers:
 
 ```ts
 up: (schema) =>
-  schema.raw("CREATE INDEX idx_posts_user ON posts (user_id)"),
+  schema.alterTable("users", (t) => {
+    t.string("phone").nullable();     // ADD COLUMN
+    t.renameColumn("name", "full_name");
+    t.index("phone");
+    t.dropIndex("users_legacy_index");
+    t.dropColumn("legacy");
+  }),
+```
+
+For anything the builder still doesn't cover, `schema.raw(sql, bindings?)` runs
+arbitrary SQL:
+
+```ts
+up: (schema) => schema.raw("CREATE INDEX idx_posts_user ON posts (user_id)"),
 ```
 
 > `raw()` writes through the connection **without** placeholder conversion, so

package/docs/models.md

@@ -173,6 +173,85 @@ return json(user);       // works directly — json() serializes it
 user.fill({ name: "X" }); // merge mass-assignable attributes without saving
 ```
 
+Control what `toJSON()` exposes with three statics. `hidden` strips columns;
+`visible` is an allowlist that wins over everything; `appends` adds computed
+attributes — a getter or a zero-arg method on the model:
+
+```ts
+class User extends Model {
+  static table = "users";
+  static hidden = ["password"];       // never serialized
+  static appends = ["fullName"];      // added to the output
+  get fullName() { return `${this.first} ${this.last}`; }
+}
+```
+
+## Lifecycle events
+
+A model fires events as it is retrieved, saved, and deleted. Hook onto them to
+slug a title, bust a cache, or cascade — without touching every call site. The
+`*ing` events are **cancelable**: a hook returning `false` aborts the write.
+
+```ts
+User.creating((user) => { user.uuid = crypto.randomUUID(); });
+User.saved((user) => cache().forget(`user:${user.id}`));
+User.deleting((user) => (user.isRoot ? false : undefined)); // veto
+
+// Or group them in an observer:
+User.observe({
+  creating: (u) => { u.uuid = crypto.randomUUID(); },
+  deleted:  (u) => audit(`deleted ${u.id}`),
+});
+```
+
+Events: `retrieved`, `creating`/`created`, `updating`/`updated`,
+`saving`/`saved`, `deleting`/`deleted`, `restoring`/`restored`. They're keyed by
+the exact class (subclasses don't inherit a parent's hooks).
+
+## Query scopes
+
+A **global scope** constrains every query a model builds — the base for
+multi-tenancy, published-only reads, and soft deletes:
+
+```ts
+Post.addGlobalScope("published", (q) => q.where("published", true));
+await Post.all();        // only published
+await Post.query().where("author_id", 1).get();  // still only published
+```
+
+A **local scope** is just a static method returning a query — no framework
+feature needed:
+
+```ts
+class Post extends Model {
+  static popular() { return this.query().where("views", ">", 1000); }
+}
+await Post.popular().orderBy("views", "desc").get();
+```
+
+## Soft deletes
+
+Opt in with `static softDeletes = true` and a `deleted_at` column. `delete()`
+then sets the timestamp instead of removing the row, and a global scope hides
+soft-deleted rows from every query.
+
+```ts
+class User extends Model {
+  static table = "users";
+  static softDeletes = true;
+  static casts = { deleted_at: "date" };
+}
+
+await user.delete();          // sets deleted_at; row stays in the table
+user.trashed();               // true
+await User.find(user.id);     // null — hidden by the scope
+
+await User.withTrashed().get();   // include soft-deleted
+await User.onlyTrashed().get();   // only soft-deleted
+await user.restore();             // clear deleted_at
+await user.forceDelete();         // remove the row for good
+```
+
 ## Relationships
 
 Define a relationship as a method that returns one of `hasMany` / `hasOne` /
@@ -222,6 +301,29 @@ users[0].toJSON();             // includes `posts` and `roles`
 Loaded relations are stored off the model, so they never leak into `save()`,
 and `toJSON()` serializes them (nested models included).
 
+### Querying relationships (`with`, `withCount`, `whereHas`)
+
+`Model.query()` returns a model-aware builder with the relationship operations a
+raw query can't express. `with()` eager-loads (dotted paths nest), `withCount()`
+adds a `<relation>_count`, and `has`/`whereHas`/`doesntHave` filter by whether a
+related row exists:
+
+```ts
+const users = await User.query()
+  .where("active", true)
+  .with("posts.comments")                       // nested eager load
+  .withCount("posts")                            // users[i].posts_count
+  .whereHas("posts", (q) => q.where("published", true))
+  .get();
+
+await User.has("posts").get();        // users with at least one post
+await User.doesntHave("posts").get(); // users with none
+```
+
+`with`/`withCount`/`whereHas`/`has`/`doesntHave` are also static shortcuts
+(`User.with(...)`, `User.whereHas(...)`). Existence filters use the same
+driver-agnostic two-query strategy as the relations themselves — no JOIN.
+
 ### Many-to-many
 
 `belongsToMany` reads through a pivot table (default name: the two table names
@@ -242,11 +344,39 @@ this.belongsTo(User, "owner_id", "id");
 this.belongsToMany(Role, "user_roles", "user_id", "role_id");
 ```
 
+### Polymorphic
+
+A polymorphic relation lets one model belong to more than one type. The related
+rows carry `<name>_id` + `<name>_type`; register each owner type so `morphTo`
+can resolve it:
+
+```ts
+class Post extends Model {
+  comments() { return this.morphMany(Comment, "commentable"); }
+}
+class Video extends Model {
+  comments() { return this.morphMany(Comment, "commentable"); }
+}
+class Comment extends Model {
+  commentable() { return this.morphTo("commentable"); } // resolves back to Post or Video
+}
+
+registerMorphType("Post", Post);
+registerMorphType("Video", Video);
+
+await post.comments().create({ body: "nice" }); // sets commentable_id/_type
+const owner = await comment.commentable();       // Post | Video | null
+```
+
+`morphOne` is the one-to-one variant. Eager loading (`Model.load` / `with`) works
+across mixed types.
+
 ## What this is (and isn't)
 
-This is a deliberately small active-record — enough for CRUD, relationships,
-casts, and simple queries without an ORM dependency. Nested eager loading
-(`posts.comments`) and query-time `with()` aren't here yet. For complex schemas
+This is a compact active-record — CRUD, lifecycle events, scopes, soft deletes,
+serialization control, eager loading (including nested `with("posts.comments")`),
+relationship queries (`whereHas`/`withCount`), and polymorphic relations — all on
+a driver-agnostic query builder, no ORM dependency. For complex one-off queries
 you can always drop to `db()` or your driver directly.
 
 ---