@shaferllc/keel 0.81.2 → 0.83.0

package/dist/teams/models.js

@@ -56,14 +56,38 @@ export async function memberOf(userId, teamId, atLeast = "member") {
  * leave the owner out of every membership query.
  */
 export async function createTeam(name, ownerId, slug) {
-    const team = await Team.create({
-        name,
-        slug: slug ?? slugify(name),
-        owner_id: ownerId,
-    });
+    let team;
+    // Retry on the unique index, don't just look before leaping.
+    //
+    // Picking a free slug with a SELECT is a check-then-act race: two people called
+    // Ada signing up at the same moment both see "ada-s-team" is free, and one of them
+    // gets a constraint error instead of an account. The index is the only real
+    // arbiter, so the fix is to let it arbitrate and try again — not to look harder.
+    for (let attempt = 0; attempt < 5; attempt++) {
+        const candidate = slug ?? (await uniqueSlug(slugify(name)));
+        try {
+            team = (await Team.create({ name, slug: candidate, owner_id: ownerId }));
+            break;
+        }
+        catch (error) {
+            // An explicit slug was asked for and taken: that's the caller's problem.
+            if (slug || !isUniqueViolation(error))
+                throw error;
+        }
+    }
+    if (!team)
+        throw new Error(`Could not find a free slug for "${name}".`);
     await Membership.create({ team_id: team.id, user_id: ownerId, role: "owner" });
     return team;
 }
+/** Every driver phrases it differently, and none of them agree on an error code. */
+function isUniqueViolation(error) {
+    const message = String(error?.message ?? error);
+    return (/unique/i.test(message) || // sqlite / libsql / d1
+        /duplicate key/i.test(message) || // postgres
+        /duplicate entry/i.test(message) // mysql
+    );
+}
 /**
  * Switch which team a user is acting as — **only** to a team they're actually in.
  *
@@ -77,6 +101,28 @@ export async function switchTeam(userId, teamId, userTable = "users") {
     await db(userTable).where("id", userId).update({ current_team_id: teamId });
     return true;
 }
+/**
+ * A slug nobody else has taken.
+ *
+ * `teams.slug` is unique, and personal teams are named after their owner — so two
+ * people called Ada would collide and the second one's signup would 500. Names are
+ * not unique and were never going to be; the slug has to make itself so.
+ */
+async function uniqueSlug(base) {
+    const stem = base || "team";
+    // The unique index is still the real guarantee; this just avoids the collision in
+    // the common case rather than surfacing a constraint error to someone signing up.
+    const taken = new Set((await db(Team.table).where("slug", "like", `${stem}%`).get()).map((row) => String(row.slug)));
+    if (!taken.has(stem))
+        return stem;
+    for (let n = 2; n < 1000; n++) {
+        const candidate = `${stem}-${n}`;
+        if (!taken.has(candidate))
+            return candidate;
+    }
+    // A thousand teams called the same thing. Fine — stop counting.
+    return `${stem}-${crypto.randomUUID().slice(0, 8)}`;
+}
 function slugify(name) {
     return name
         .toLowerCase()

package/docs/ai-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.81.2",
+  "version": "0.83.0",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "repo": "https://github.com/shaferllc/keel",
   "generated": "run `npm run build:ai` to regenerate",
@@ -271,6 +271,13 @@
       "path": "docs/openapi.md",
       "example": null
     },
+    {
+      "slug": "orm",
+      "title": "ORM",
+      "summary": "Keel's ORM is a compact active record over the query builder: a model is a class pointed at a table, and its rows come back as typed objects with methods.",
+      "path": "docs/orm.md",
+      "example": null
+    },
     {
       "slug": "packages",
       "title": "Packages",
@@ -292,6 +299,13 @@
       "path": "docs/providers.md",
       "example": "docs/examples/providers.ts"
     },
+    {
+      "slug": "query-builder",
+      "title": "Query Builder",
+      "summary": "Keel's driver-agnostic query builder — build and run SQL by chaining methods off db(table).",
+      "path": "docs/query-builder.md",
+      "example": null
+    },
     {
       "slug": "queues",
       "title": "Queues & Jobs",
@@ -355,6 +369,13 @@
       "path": "docs/social-auth.md",
       "example": null
     },
+    {
+      "slug": "starter-kits",
+      "title": "Starter kits",
+      "summary": "",
+      "path": "docs/starter-kits.md",
+      "example": null
+    },
     {
       "slug": "static-files",
       "title": "Static Files",
@@ -2811,6 +2832,11 @@
       "kind": "value",
       "module": "storage"
     },
+    {
+      "name": "SimplePaginated",
+      "kind": "type",
+      "module": "database"
+    },
     {
       "name": "singleton",
       "kind": "value",

package/docs/database.md

@@ -110,106 +110,12 @@ An unregistered connection name doesn't fail when you *build* a query, only when
 it runs — so a misconfigured name surfaces as a rejected read/write, not a
 construction-time throw.
 
-## Querying
+## Queries & models
 
-Start a query with `db(table)`, chain constraints, and finish with a terminal
-method (`get`, `first`, `count`, `exists`):
-
-```ts
-import { db } from "@shaferllc/keel/core";
-
-await db("users").where("active", true).orderBy("name").get();
-await db("users").where("id", 1).first();          // row | null
-await db("users").where("age", ">", 18).count();
-await db("posts").whereIn("id", [1, 2, 3]).get();
-await db("posts").whereNull("deleted_at").limit(20).offset(40).get();
-
-await db("orders")
-  .select("id", "total")
-  .where("status", "paid")
-  .orWhere("status", "shipped")
-  .get();
-```
-
-Constraint methods return the builder, so they chain in any order; the query
-isn't sent until you call a terminal method. Multiple `where` calls combine with
-`AND`; `orWhere` joins with `OR`.
-
-More `where` clauses and ordering shortcuts:
-
-```ts
-await db("posts").whereBetween("views", [10, 100]).get();
-await db("posts").whereNotIn("id", [4, 5]).get();
-await db("posts").whereLike("title", "%keel%").get();
-await db("posts").latest().get();          // ORDER BY created_at DESC
-await db("posts").oldest("published_at").get();
-```
-
-Joins, grouping, and conditional/raw clauses:
-
-```ts
-await db("posts")
-  .join("users", "posts.user_id", "users.id")   // also leftJoin(...)
-  .select("posts.title", "users.name")
-  .get();
-
-await db("posts").select("user_id").groupBy("user_id").having("COUNT(*)", ">", 5).get();
-await db("users").distinct().select("country").pluck("country");
-
-await db("events").whereColumn("updated_at", ">", "created_at").get();
-await db("users").whereRaw("score >= ?", [10]).orderByRaw("LENGTH(name) DESC").get();
-
-await db("users").when(search, (q, term) => q.whereLike("name", `%${term}%`)).get();
-```
-
-## Aggregates, single values, and pagination
-
-```ts
-await db("orders").where("paid", true).sum("total");   // number
-await db("orders").avg("total");
-await db("orders").min("total");
-await db("orders").max("total");
-
-await db("users").where("id", 1).value("email");        // one column, first row
-await db("posts").pluck("title");                        // string[] of one column
-
-const page = await db("posts").latest().paginate(2, 15); // { data, total, perPage, currentPage, lastPage }
-```
-
-`paginate(page, perPage)` runs a `COUNT` then a `LIMIT`/`OFFSET` query and returns
-a `Paginated<T>` with the page and the metadata to render pager controls.
-
-## Writing
-
-```ts
-const id = await db("users").insertGetId({ email, name });
-await db("users").where("id", id).update({ name: "Grace" });
-await db("users").where("id", id).delete();
-```
-
-Everything is parameterized — values become bindings, never string-interpolated
-SQL — so it's injection-safe by construction. Writes return a `WriteResult`;
-`insertGetId` unwraps it to just the new id.
-
-Counters, bulk upserts, and paged iteration:
-
-```ts
-await db("posts").where("id", id).increment("views");        // += 1
-await db("posts").where("id", id).decrement("stock", 3, { updated_at: now });
-
-// Insert, updating the listed columns on a unique-key conflict (dialect-aware).
-await db("users").upsert([{ id: 1, name: "Ada" }], ["id"], ["name"]);
-await db("logs").insertOrIgnore({ key, value });             // skip duplicates
-
-// Process a large table a page at a time (return false to stop early).
-await db("users").orderBy("id").chunk(500, async (rows) => {
-  for (const row of rows) await process(row);
-});
-```
-
-> **Guard your writes.** `update()` and `delete()` apply to every row that
-> matches the current `where` clause — with no `where`, that's the whole table.
-> Always scope a write with `where` unless you truly mean to touch every row.
+Building and running queries — `where`, joins, aggregates, inserts, updates,
+pagination — lives in the [Query Builder](./query-builder.md) guide. The
+[ORM](./orm.md) adds an active-record layer (models, relationships, events,
+scopes) on top of the same builder.
 
 ## Transactions
 
@@ -407,255 +313,6 @@ unnamed `db(table)` and connectionless models use (throws if `name` isn't
 registered). `connectionNames()` returns the registered names.
 `clearConnections()` unregisters everything — a test helper.
 
-### `QueryBuilder`
-
-Returned by `db()`. Constraint methods return `this` (chainable); terminal
-methods return a promise. You never construct it directly.
-
-#### `select(...columns)`
-
-`select(...columns: string[]): this`
-
-Restricts the selected columns. With no arguments, selects `*`.
-
-```ts
-db("users").select("id", "email").get();
-```
-
-**Notes:** column names are interpolated as-is (they are not parameterized), so
-never pass user input as a column name. Calling it again replaces the prior
-selection.
-
-#### `where(column, value)` / `where(column, operator, value)`
-
-`where(column: string, value: unknown): this`
-`where(column: string, operator: Operator, value: unknown): this`
-
-Adds an `AND` condition. The two-argument form uses `=`; the three-argument form
-takes an explicit operator.
-
-```ts
-db("users").where("active", true);
-db("users").where("age", ">", 18);
-db("users").where("email", "like", "%@example.com");
-```
-
-**Notes:** `Operator` is `"=" | "!=" | "<" | "<=" | ">" | ">=" | "like"`. Values
-are always parameterized. Chaining multiple `where`s combines them with `AND`.
-
-#### `orWhere(column, value)` / `orWhere(column, operator, value)`
-
-`orWhere(column: string, value: unknown): this`
-`orWhere(column: string, operator: Operator, value: unknown): this`
-
-Same as `where`, but joins the condition with `OR`.
-
-```ts
-db("orders").where("status", "paid").orWhere("status", "shipped").get();
-```
-
-**Notes:** conditions are combined left-to-right without grouping parentheses, so
-mixing `where` and `orWhere` follows SQL's `AND`/`OR` precedence — group complex
-logic in separate queries if you need explicit parenthesization.
-
-#### `whereIn(column, values)`
-
-`whereIn(column: string, values: unknown[]): this`
-
-Matches rows where `column` is any of `values` (`AND`-joined).
-
-```ts
-db("posts").whereIn("id", [1, 2, 3]).get();
-```
-
-**Notes:** each value becomes its own placeholder. An empty array produces
-`IN ()`, which most engines reject — guard against empty lists yourself.
-
-#### `whereNull(column)` / `whereNotNull(column)`
-
-`whereNull(column: string): this`
-`whereNotNull(column: string): this`
-
-Adds an `AND` `IS NULL` / `IS NOT NULL` condition — no binding.
-
-```ts
-db("posts").whereNull("deleted_at").get();
-db("users").whereNotNull("verified_at").get();
-```
-
-#### `orderBy(column, direction?)`
-
-`orderBy(column: string, direction?: "asc" | "desc"): this`
-
-Adds an `ORDER BY` clause (default `"asc"`). Call it repeatedly for multiple sort
-keys, applied in call order.
-
-```ts
-db("users").orderBy("last_name").orderBy("created_at", "desc").get();
-```
-
-**Notes:** the column is interpolated, not parameterized — don't pass user input.
-
-#### `limit(n)` / `offset(n)`
-
-`limit(n: number): this`
-`offset(n: number): this`
-
-Caps the number of rows / skips the first `n`. Together they paginate.
-
-```ts
-db("posts").limit(20).offset(40).get(); // page 3, 20 per page
-```
-
-**Notes:** `first()` sets `limit(1)` internally, overriding any prior `limit`.
-
-#### `get()`
-
-`get(): Promise<T[]>`
-
-Runs the SELECT and returns all matching rows.
-
-```ts
-const rows = await db("users").where("active", true).get();
-```
-
-#### `first()`
-
-`first(): Promise<T | null>`
-
-Runs the SELECT with `LIMIT 1` and returns the first row, or `null`.
-
-```ts
-const user = await db("users").where("email", email).first();
-```
-
-**Notes:** overrides any `limit` you set. Returns `null` (not `undefined`) when
-nothing matches.
-
-#### `count()`
-
-`count(): Promise<number>`
-
-Returns `COUNT(*)` for the current `where` clause.
-
-```ts
-const active = await db("users").where("active", true).count();
-```
-
-**Notes:** ignores `select`, `orderBy`, `limit`, and `offset` — it counts matching
-rows, not the paginated slice.
-
-#### `exists()`
-
-`exists(): Promise<boolean>`
-
-`true` when at least one row matches — a `count() > 0` shorthand.
-
-```ts
-if (await db("users").where("email", email).exists()) { /* taken */ }
-```
-
-#### `insert(data)`
-
-`insert(data: Row): Promise<WriteResult>`
-
-Inserts one row and returns write metadata.
-
-```ts
-const result = await db("users").insert({ email, name });
-result.rowsAffected; // 1
-result.insertId;     // driver-dependent
-```
-
-**Notes:** column order follows `Object.keys(data)`. `insertId` is only populated
-if the driver reports it in `WriteResult`.
-
-#### `insertGetId(data)`
-
-`insertGetId(data: Row): Promise<number | string | undefined>`
-
-Inserts one row and returns just its new id (`insert` unwrapped).
-
-```ts
-const id = await db("users").insertGetId({ email, name });
-```
-
-**Notes:** returns `undefined` when the driver doesn't report an `insertId`.
-
-#### `update(data)`
-
-`update(data: Row): Promise<WriteResult>`
-
-Updates every row matching the `where` clause, setting the given columns.
-
-```ts
-const r = await db("users").where("id", 1).update({ name: "Grace" });
-r.rowsAffected; // rows changed
-```
-
-**Notes:** with no `where`, updates the entire table. Bindings are the new values
-followed by the where-clause values.
-
-#### `delete()`
-
-`delete(): Promise<WriteResult>`
-
-Deletes every row matching the `where` clause.
-
-```ts
-await db("sessions").where("expires_at", "<", now).delete();
-```
-
-**Notes:** with no `where`, empties the table. There's no soft-delete here — pair
-with a `deleted_at` column and `whereNull` if you want one.
-
-#### `whereColumn(first, operator?, second)` · `whereRaw(sql, bindings?)`
-
-Compare two columns (no binding) or add a raw WHERE fragment with its own
-bindings. `whereColumn("updated_at", ">", "created_at")`; `whereRaw("score >= ?", [10])`.
-
-#### `join(table, first, operator?, second)` · `leftJoin(...)`
-
-Add an `INNER JOIN` / `LEFT JOIN` on an equality (or the given operator).
-Included in `get`, `count`, and aggregates. Qualify ambiguous columns
-(`"posts.user_id"`).
-
-#### `groupBy(...columns)` · `having(column, operator?, value)` · `distinct()`
-
-`GROUP BY`, a bound `HAVING` predicate, and `SELECT DISTINCT`.
-
-#### `orderByRaw(sql)` · `when(condition, then, otherwise?)`
-
-A raw `ORDER BY` fragment; and conditional building — `then(query, value)` runs
-only when `condition` is truthy, else `otherwise`.
-
-#### `increment(column, amount?, extra?)` · `decrement(column, amount?, extra?)`
-
-`increment(column: string, amount = 1, extra: Row = {}): Promise<WriteResult>`
-
-Atomically `column = column ± amount` on matching rows, optionally setting other
-columns in the same statement. Scope with `where`.
-
-#### `upsert(rows, uniqueBy, update?)`
-
-`upsert(rows: Row | Row[], uniqueBy: string[], update?: string[]): Promise<WriteResult>`
-
-Insert rows, updating `update` columns (default: all non-unique) on a conflict
-against `uniqueBy`. Dialect-aware: `ON CONFLICT … DO UPDATE` (sqlite/postgres) or
-`ON DUPLICATE KEY UPDATE` (mysql).
-
-#### `insertOrIgnore(rows)`
-
-Insert one or more rows, skipping any that violate a unique constraint
-(`INSERT OR IGNORE` / `INSERT IGNORE` / `ON CONFLICT DO NOTHING`).
-
-#### `chunk(size, callback)`
-
-`chunk(size: number, callback: (rows: T[]) => void | boolean | Promise<void | boolean>): Promise<void>`
-
-Process results a page at a time so a large table never loads at once. Return
-`false` from the callback to stop early. Pair with `orderBy` for a stable order.
-
 ### Interfaces & types
 
 #### `Connection`

package/docs/models.md

@@ -205,8 +205,11 @@ User.observe({
 ```
 
 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).
+`saving`/`saved`, `deleting`/`deleted`, `restoring`/`restored`.
+
+Hooks **inherit**, ancestors first: a hook on a base class fires for every model
+that extends it. That's what lets a base class do real work — a `creating` hook
+that stamps a tenant id is useless if subclasses never fire it.
 
 ## Query scopes
 

package/docs/orm.md

@@ -0,0 +1,57 @@
+# ORM
+
+Keel's ORM is a compact **active record** over the [query builder](./query-builder.md):
+a model is a class pointed at a table, and its rows come back as typed objects
+with methods. There's no mapper to configure and no separate schema layer — a
+model *is* the row plus behaviour. It runs on whatever [connection](./database.md)
+you registered, so the same code works on Node and the edge.
+
+```ts
+import { Model } from "@shaferllc/keel/core";
+
+class User extends Model {
+  static table = "users";
+  declare id: number;
+  declare email: string;
+
+  posts() { return this.hasMany(Post); }
+}
+
+const user = await User.find(1);
+await user.posts();                 // relations are awaitable
+if (await user.subscribed()) { /* … */ }
+```
+
+This page is the map; each capability has a deep-dive in **[Models](./models.md)**.
+
+## What the ORM gives you
+
+| Area | What you get | Guide |
+|------|--------------|-------|
+| **CRUD** | `find` / `all` / `create` / `save` / `update` / `delete`, `firstOrCreate`, `updateOrCreate` | [Models → Reading/Writing](./models.md#reading) |
+| **Casts** | `boolean` / `int` / `json` / `date` … columns round-trip as real JS types | [Models → Attribute casts](./models.md#attribute-casts) |
+| **Mass assignment** | `fillable` / `guarded` allow/deny lists guard untrusted input | [Models → Mass assignment](./models.md#mass-assignment) |
+| **Serialization** | `hidden` / `visible` / `appends` shape `toJSON()` | [Models → Serializing](./models.md#serializing) |
+| **Relationships** | `hasOne` / `hasMany` / `belongsTo` / `belongsToMany` + polymorphic `morphOne` / `morphMany` / `morphTo` | [Models → Relationships](./models.md#relationships) |
+| **Eager loading** | `with("posts.comments")` (nested), `withCount`, `Model.load` — no N+1 | [Models → Eager loading](./models.md#eager-loading-avoiding-n1) |
+| **Relationship queries** | `whereHas` / `has` / `doesntHave` | [Models → Querying relationships](./models.md#querying-relationships-with-withcount-wherehas) |
+| **Lifecycle events** | `creating`/`saved`/`deleting`/… hooks and observers, inherited by subclasses | [Models → Lifecycle events](./models.md#lifecycle-events) |
+| **Scopes** | global scopes (tenancy, published-only) + local scope methods | [Models → Query scopes](./models.md#query-scopes) |
+| **Soft deletes** | `deleted_at`, `withTrashed` / `onlyTrashed` / `restore` / `forceDelete` | [Models → Soft deletes](./models.md#soft-deletes) |
+
+## How it relates to the rest
+
+- The **[query builder](./query-builder.md)** is the layer underneath. `Model.query()`
+  returns a model-aware builder, and everything an ORM query can't express
+  (raw joins, aggregates, bulk writes) is one `db()` call away.
+- **[Migrations](./migrations.md)** define the tables models read and write.
+- **[Factories & seeders](./factories.md)** generate model rows for tests and demos.
+- **[API resources](./api-resources.md)** turn models into a REST API; **[transformers](./transformers.md)**
+  control their serialized shape at the boundary.
+
+## When to drop down
+
+The ORM is deliberately small — enough for CRUD, relationships, and the common
+query shapes without an ORM dependency. For a gnarly one-off report, reach for
+the [query builder](./query-builder.md) or a raw `connection().select(sql)`; the
+model layer never gets in the way.