@shaferllc/keel 0.82.0 → 0.83.0

package/dist/db/d1-http.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A Keel `Connection` for Cloudflare D1 over its **HTTP API**.
+ *
+ * The D1 binding (`env.DB`) only exists inside a running Worker, which leaves an
+ * awkward hole: `keel migrate` runs on your laptop and in CI, where there is no
+ * binding — so there was no way to create your tables. This closes it. Same
+ * `Connection` interface, so migrations, models, and the query builder all work
+ * against a real D1 database from anywhere:
+ *
+ *   import { d1HttpConnection } from "@shaferllc/keel/db/d1-http";
+ *
+ *   setConnection(d1HttpConnection({
+ *     accountId: env("CLOUDFLARE_ACCOUNT_ID"),
+ *     databaseId: env("D1_DATABASE_ID"),
+ *     apiToken: env("CLOUDFLARE_API_TOKEN"),
+ *   }), "sqlite");
+ *
+ * Use the **binding** (`@shaferllc/keel/db/d1`) inside the Worker — it's a direct
+ * call with no network hop. Use this one for migrations and scripts. Both speak
+ * SQLite, so the same schema serves both.
+ *
+ * `fetch` only — no SDK, nothing Node-specific.
+ */
+import type { Connection } from "../core/database.js";
+export interface D1HttpOptions {
+    accountId: string;
+    databaseId: string;
+    /** An API token with D1 edit permission. */
+    apiToken: string;
+    /** Override the API base (for tests, or a proxy). */
+    baseUrl?: string;
+}
+/** Build a `Connection` that talks to D1 over HTTP. */
+export declare function d1HttpConnection(options: D1HttpOptions): Connection;

package/dist/db/d1-http.js

@@ -0,0 +1,61 @@
+/**
+ * A Keel `Connection` for Cloudflare D1 over its **HTTP API**.
+ *
+ * The D1 binding (`env.DB`) only exists inside a running Worker, which leaves an
+ * awkward hole: `keel migrate` runs on your laptop and in CI, where there is no
+ * binding — so there was no way to create your tables. This closes it. Same
+ * `Connection` interface, so migrations, models, and the query builder all work
+ * against a real D1 database from anywhere:
+ *
+ *   import { d1HttpConnection } from "@shaferllc/keel/db/d1-http";
+ *
+ *   setConnection(d1HttpConnection({
+ *     accountId: env("CLOUDFLARE_ACCOUNT_ID"),
+ *     databaseId: env("D1_DATABASE_ID"),
+ *     apiToken: env("CLOUDFLARE_API_TOKEN"),
+ *   }), "sqlite");
+ *
+ * Use the **binding** (`@shaferllc/keel/db/d1`) inside the Worker — it's a direct
+ * call with no network hop. Use this one for migrations and scripts. Both speak
+ * SQLite, so the same schema serves both.
+ *
+ * `fetch` only — no SDK, nothing Node-specific.
+ */
+/** Build a `Connection` that talks to D1 over HTTP. */
+export function d1HttpConnection(options) {
+    const base = options.baseUrl ?? "https://api.cloudflare.com/client/v4";
+    const url = `${base}/accounts/${options.accountId}/d1/database/${options.databaseId}/query`;
+    async function query(sql, params) {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${options.apiToken}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({ sql, params }),
+        });
+        const payload = (await response.json());
+        if (!response.ok || !payload.success) {
+            // Cloudflare returns its errors in the body with a 200 as often as not, so
+            // the status alone is not enough to tell whether the statement ran.
+            const message = payload.errors?.map((e) => `${e.code}: ${e.message}`).join("; ") ??
+                `D1 request failed (${response.status})`;
+            throw new Error(`D1: ${message}`);
+        }
+        return payload.result;
+    }
+    return {
+        async select(sql, bindings) {
+            const result = await query(sql, bindings);
+            return result?.[0]?.results ?? [];
+        },
+        async write(sql, bindings) {
+            const result = await query(sql, bindings);
+            const meta = result?.[0]?.meta ?? {};
+            return {
+                rowsAffected: meta.changes ?? meta.rows_written ?? 0,
+                insertId: meta.last_row_id != null ? Number(meta.last_row_id) : undefined,
+            };
+        },
+    };
+}

package/dist/db/libsql.d.ts

@@ -13,14 +13,24 @@
  * The client is duck-typed — this module imports no driver, so it never bundles
  * `@libsql/client`.
  */
-import type { Connection, Row } from "../core/database.js";
+import type { Connection } from "../core/database.js";
 /** The slice of the `@libsql/client` API this adapter uses. */
 export interface LibSqlLike {
+    /**
+     * `any` rather than `unknown[]` / `Row[]` on purpose.
+     *
+     * The official client types its arguments as `InArgs` and its rows as its own
+     * `Row`, and under `strictFunctionTypes` a narrower parameter type makes the real
+     * `Client` *unassignable* to this interface — so wiring libSQL the obvious way
+     * required `client as unknown as LibSqlLike`, which is a cast a user shouldn't
+     * have to discover. Widening here keeps `libsqlConnection(createClient(…))`
+     * working with no ceremony; the values are normalized below anyway.
+     */
     execute(stmt: {
         sql: string;
-        args: unknown[];
+        args: any[];
     }): Promise<{
-        rows: Row[];
+        rows: any[];
         rowsAffected: number;
         lastInsertRowid?: bigint | number;
     }>;

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.82.0",
+  "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",