weifuwu 0.23.2 → 0.23.4

package/dist/index.js

@@ -28,6 +28,9 @@ function traceElapsed() {
 // env.ts
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+function isBundled() {
+  return true ? true : false;
+}
 function isDev() {
   return process.env.NODE_ENV === "development";
 }
@@ -1619,22 +1622,6 @@ function compress(options) {
 }
 
 // helmet.ts
-var DEFAULTS = {
-  contentSecurityPolicy: "default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests",
-  crossOriginEmbedderPolicy: "require-corp",
-  crossOriginOpenerPolicy: "same-origin",
-  crossOriginResourcePolicy: "same-origin",
-  originAgentCluster: "?1",
-  referrerPolicy: "no-referrer",
-  strictTransportSecurity: "max-age=15552000; includeSubDomains",
-  xContentTypeOptions: "nosniff",
-  xDnsPrefetchControl: "off",
-  xDownloadOptions: "noopen",
-  xFrameOptions: "SAMEORIGIN",
-  xPermittedCrossDomainPolicies: "none",
-  xXssProtection: "0",
-  permissionsPolicy: "camera=(),display-capture=(),fullscreen=(),geolocation=(),microphone=()"
-};
 var HEADER_MAP = {
   "Content-Security-Policy": "contentSecurityPolicy",
   "Cross-Origin-Embedder-Policy": "crossOriginEmbedderPolicy",
@@ -1667,6 +1654,22 @@ function helmet(options) {
     return new Response(res.body, { status: res.status, statusText: res.statusText, headers: h });
   };
 }
+var DEFAULTS = {
+  contentSecurityPolicy: "default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests",
+  crossOriginEmbedderPolicy: "require-corp",
+  crossOriginOpenerPolicy: "same-origin",
+  crossOriginResourcePolicy: "same-origin",
+  originAgentCluster: "?1",
+  referrerPolicy: "no-referrer",
+  strictTransportSecurity: "max-age=15552000; includeSubDomains",
+  xContentTypeOptions: "nosniff",
+  xDnsPrefetchControl: "off",
+  xDownloadOptions: "noopen",
+  xFrameOptions: "SAMEORIGIN",
+  xPermittedCrossDomainPolicies: "none",
+  xXssProtection: "0",
+  permissionsPolicy: "camera=(),display-capture=(),fullscreen=(),geolocation=(),microphone=()"
+};
 
 // request-id.ts
 import crypto2 from "node:crypto";
@@ -2474,12 +2477,15 @@ import postgresFactory from "postgres";
 
 // postgres/schema/sql.ts
 var SQL = class {
+  /** Template string parts (interleaved with values). */
   strings;
+  /** Bound parameter values. */
   values;
   constructor(strings, values) {
     this.strings = strings;
     this.values = values;
   }
+  /** Serialize to a raw SQL string (interpolating values inline for DDL use). */
   toSQL() {
     let result = "";
     for (let i = 0; i < this.strings.length; i++) {
@@ -2497,31 +2503,43 @@ function sql(strings, ...values) {
 
 // postgres/schema/columns.ts
 var ColumnBuilder = class {
+  /** Column name. */
   name;
+  /** SQL type string (e.g. `'TEXT'`, `'INTEGER'`). */
   sqlType;
+  /** Whether this column is PRIMARY KEY. */
   isPrimaryKey = false;
+  /** Whether this column allows NULL. */
   isNullable = true;
+  /** Whether this column has a UNIQUE constraint. */
   isUnique = false;
+  /** Whether the value is auto-generated (e.g. SERIAL, UUID defaults). */
   isAutoGenerate = false;
+  /** DEFAULT expression as a raw SQL string. */
   defaultExpr = null;
+  /** Foreign key reference, if any. */
   ref = null;
   constructor(name, sqlType) {
     this.name = name;
     this.sqlType = sqlType;
   }
+  /** Mark as PRIMARY KEY (implies NOT NULL). */
   primaryKey() {
     this.isPrimaryKey = true;
     this.isNullable = false;
     return this;
   }
+  /** Add NOT NULL constraint. */
   notNull() {
     this.isNullable = false;
     return this;
   }
+  /** Allow NULL values (default). */
   nullable() {
     this.isNullable = true;
     return this;
   }
+  /** Set a DEFAULT value. Accepts raw SQL, string, number, or boolean. */
   default(expr) {
     if (expr instanceof SQL) {
       this.defaultExpr = expr.toSQL();
@@ -2532,10 +2550,12 @@ var ColumnBuilder = class {
     }
     return this;
   }
+  /** Add UNIQUE constraint. */
   unique() {
     this.isUnique = true;
     return this;
   }
+  /** Add FOREIGN KEY reference to another table. */
   references(table, column = "id", onDelete) {
     this.ref = { table, column, onDelete };
     return this;
@@ -2629,8 +2649,11 @@ function and(...conditions) {
 
 // postgres/schema/table.ts
 var Table = class {
+  /** Database table name. */
   tableName;
+  /** All column builders (order-preserving). */
   columns;
+  /** Column builders keyed by property name. */
   builders;
   colEntries;
   constructor(tableName, builders) {
@@ -2644,10 +2667,14 @@ var Table = class {
       column: col2
     }));
   }
+  /** Check if the table has a column with the given DB name. */
   hasColumn(dbName) {
     return this.colEntries.some((e) => e.db === dbName);
   }
-  /** Returns a BoundTable pre-bound to the given sql connection (no need to pass sql to every method). */
+  /**
+   * Bind this table schema to a SQL connection, returning a `BoundTable`
+   * that can run queries without passing `sql` to every call.
+   */
   bind(sql2) {
     return new BoundTable(sql2, this.tableName, this.builders);
   }
@@ -3772,6 +3799,18 @@ function user(options) {
       return null;
     }
   }
+  function extractToken(req, cookieName) {
+    const header = req.headers.get("Authorization");
+    if (header?.startsWith("Bearer ")) return header.slice(7);
+    if (cookieName) {
+      const cookies = req.headers.get("cookie")?.split(";").map((c) => c.trim()).filter(Boolean) || [];
+      for (const c of cookies) {
+        const eq2 = c.indexOf("=");
+        if (eq2 > 0 && c.slice(0, eq2) === cookieName) return c.slice(eq2 + 1);
+      }
+    }
+    return null;
+  }
   function middleware() {
     return async (req, ctx, next) => {
       const sessionUserId = ctx.session?.userId;
@@ -3788,8 +3827,7 @@ function user(options) {
           delete ctx.session?.userId;
         }
       }
-      const header = req.headers.get("Authorization");
-      const token = header?.startsWith("Bearer ") ? header.slice(7) : null;
+      const token = extractToken(req);
       if (token) {
         const userData = await verify(token);
         if (userData) {
@@ -3800,11 +3838,36 @@ function user(options) {
       return new Response("Unauthorized", { status: 401, headers: { "WWW-Authenticate": "Bearer" } });
     };
   }
+  function middlewareOptional(opts) {
+    const cookieName = opts?.cookie;
+    return async (req, ctx, next) => {
+      const token = extractToken(req, cookieName);
+      if (token) {
+        const userData = await verify(token);
+        if (userData) {
+          ctx.user = userData;
+        }
+      }
+      return next(req, ctx);
+    };
+  }
+  async function parseBody2(req) {
+    const ct = req.headers.get("content-type") || "";
+    if (ct.includes("application/json")) {
+      return req.json();
+    }
+    const form = await req.formData();
+    const obj = {};
+    for (const [key, val] of form) {
+      obj[key] = val;
+    }
+    return obj;
+  }
   function router() {
     const r2 = new Router();
     r2.post("/register", async (req) => {
       try {
-        const body = await req.json();
+        const body = await parseBody2(req);
         const result = await register(body);
         return Response.json(result, { status: 201 });
       } catch (err) {
@@ -3817,7 +3880,7 @@ function user(options) {
     });
     r2.post("/login", async (req, ctx) => {
       try {
-        const body = await req.json();
+        const body = await parseBody2(req);
         const result = await login(body);
         if (ctx.session) {
           ;
@@ -3861,6 +3924,7 @@ function user(options) {
   }
   const mod = r;
   mod.middleware = middleware;
+  mod.middlewareOptional = middlewareOptional;
   mod.migrate = migrate;
   mod.register = register;
   mod.login = login;
@@ -6717,13 +6781,24 @@ async function compileVendorBundle() {
     const keys = Object.keys(mod).filter((k) => !k.startsWith("_") && k !== "default");
     modules[request] = keys;
   }
-  const reactTsPath = resolve3(import.meta.dirname ?? __dirname, "react.ts");
-  const reactSrc = readFileSync2(reactTsPath, "utf-8");
+  const baseDir = import.meta.dirname ?? __dirname;
+  const reactAbsPath = isBundled() ? resolve3(baseDir, "react.js") : resolve3(baseDir, "react.ts");
+  const reactSrc = readFileSync2(reactAbsPath, "utf-8");
   const wfwKeys = [];
-  for (const line of reactSrc.split("\n")) {
-    const m = line.match(/^export\s+\{[^}]+\}\s*from/);
-    if (m) {
-      const names = line.slice(line.indexOf("{") + 1, line.indexOf("}")).split(",").map((s) => s.trim()).filter(Boolean);
+  if (reactAbsPath.endsWith(".ts")) {
+    for (const line of reactSrc.split("\n")) {
+      const m = line.match(/^export\s+\{[^}]+\}\s*from/);
+      if (m) {
+        const names = line.slice(line.indexOf("{") + 1, line.indexOf("}")).split(",").map((s) => s.trim()).filter(Boolean);
+        for (const n of names) {
+          if (!n.startsWith("type ") && !wfwKeys.includes(n)) wfwKeys.push(n);
+        }
+      }
+    }
+  } else {
+    const exportMatch = reactSrc.match(/\bexport\s*\{([^}]+)\}\s*;/);
+    if (exportMatch) {
+      const names = exportMatch[1].split(",").map((s) => s.trim()).filter(Boolean);
       for (const n of names) {
         if (!n.startsWith("type ") && !wfwKeys.includes(n)) wfwKeys.push(n);
       }
@@ -6736,7 +6811,7 @@ async function compileVendorBundle() {
     if (unique.length > 0) stmts.push(`export { ${unique.join(", ")} } from ${JSON.stringify(request)};`);
   }
   const uidWfw = wfwKeys.filter((k) => !used.has(k) && used.add(k));
-  if (uidWfw.length > 0) stmts.push(`export { ${uidWfw.join(", ")} } from ${JSON.stringify(reactTsPath)};`);
+  if (uidWfw.length > 0) stmts.push(`export { ${uidWfw.join(", ")} } from ${JSON.stringify(reactAbsPath)};`);
   const result = await esbuild.build({
     stdin: { contents: stmts.join("\n"), resolveDir: process.cwd() },
     format: "esm",
@@ -7105,12 +7180,6 @@ function liveRouter(dir) {
   const r = new Router();
   compileVendorBundle().catch(() => {
   });
-  r.get("/__wfw/v/bundle", async () => {
-    const code = await compileVendorBundle();
-    return new Response(code, {
-      headers: { "content-type": "application/javascript; charset=utf-8" }
-    });
-  });
   r.get("/__wfw/h/:hash", async (req, ctx) => {
     const hash = ctx.params.hash.replace(/\.js$/i, "");
     const code = hotBundleCache.get(hash);
@@ -7553,11 +7622,11 @@ function ssr(opts) {
   if (existsSync4(join5(dir, "app", "globals.css"))) {
     r.use("/", tailwindRouter(dir));
   }
+  let devWatcher;
   if (isDev2) {
     r.use("/", liveRouter(dir));
     r.ws("/__weifuwu/livereload", liveWs());
-    const watcher = liveWatcher(dir);
-    r.close = watcher.close;
+    devWatcher = liveWatcher(dir);
   }
   r.all("/*", async (req, ctx) => {
     const prefix = ctx.mountPath || "";
@@ -7566,7 +7635,17 @@ function ssr(opts) {
     const segments = relativePath.split("/").filter(Boolean);
     const resolved = await resolveRoute(dir, segments, routeCache);
     if (!resolved) {
-      return isDev2 ? Response.json({ error: "Not Found", path: "/" + segments.join("/"), method: req.method }, { status: 404 }) : new Response("Not Found", { status: 404 });
+      if (isDev2) {
+        const pages = discoverRoutes(dir).map((p) => p.path).sort();
+        return Response.json({
+          error: "Not Found",
+          path: "/" + segments.join("/"),
+          method: req.method,
+          hint: "Available SSR pages",
+          pages
+        }, { status: 404 });
+      }
+      return new Response("Not Found", { status: 404 });
     }
     const mws = [
       ...resolved.errorFiles.map((f) => errorBoundary(f)),
@@ -7578,6 +7657,7 @@ function ssr(opts) {
   });
   const mod = r;
   mod.pages = () => discoverRoutes(dir);
+  if (devWatcher) mod.close = devWatcher.close.bind(devWatcher);
   return mod;
 }
 
@@ -8929,7 +9009,6 @@ function flash(options) {
         value = raw;
       }
     }
-    ;
     ctx.flash = {
       value,
       set: makeSetFlash(name, referer)
@@ -10490,8 +10569,7 @@ function session(options) {
       await store2.set(newId, data, ttl);
       await store2.destroy(loadedSid);
       loadedSid = newId;
-      currentSession[kId] = newId;
-      currentSession[kCreatedAt] = data[kCreatedAt];
+      Object.assign(currentSession, { [kId]: newId, [kCreatedAt]: data[kCreatedAt] });
     }
     const currentData = isSessionActive(currentSession) ? JSON.stringify(currentSession) : null;
     const wasSaved = currentSession[kSaved];
@@ -11402,7 +11480,8 @@ function permissions(options) {
   });
   function requireRole(...roles) {
     return (req, ctx, next) => {
-      if (!ctx.permissions?.roles || !roles.some((r) => ctx.permissions.roles.has(r))) {
+      const p = ctx;
+      if (!p.permissions?.roles || !roles.some((r) => p.permissions.roles.has(r))) {
         return Response.json(
           { error: `Forbidden: requires one of roles [${roles.join(", ")}]` },
           { status: 403 }
@@ -11413,12 +11492,13 @@ function permissions(options) {
   }
   function requirePermission(...perms) {
     return (req, ctx, next) => {
-      const userPerms = ctx.permissions?.permissions;
+      const p = ctx;
+      const userPerms = p.permissions?.permissions;
       if (!userPerms) {
         return Response.json({ error: "Forbidden: no permissions loaded" }, { status: 403 });
       }
       if (userPerms.has("*")) return next(req, ctx);
-      const missing = perms.filter((p) => !userPerms.has(p));
+      const missing = perms.filter((p2) => !userPerms.has(p2));
       if (missing.length > 0) {
         return Response.json(
           { error: `Forbidden: missing permissions [${missing.join(", ")}]` },
@@ -11484,6 +11564,7 @@ export {
   helmet,
   i18n,
   iii,
+  isBundled,
   isDev,
   isProd,
   knowledgeBase,

package/dist/mailer.d.ts

@@ -1,20 +1,50 @@
 import type { Transporter } from 'nodemailer';
+/** Options for sending an email. */
 export interface MailOptions {
+    /** Recipient address(es). */
     to: string | string[];
+    /** Email subject. */
     subject: string;
+    /** Plain text body. */
     text?: string;
+    /** HTML body. */
     html?: string;
+    /** Sender address (overrides `MailerOptions.from`). */
     from?: string;
+    /** CC recipient(s). */
     cc?: string | string[];
+    /** BCC recipient(s). */
     bcc?: string | string[];
 }
+/** Options for {@link mailer}. */
 export interface MailerOptions {
+    /** Nodemailer transport string or pre-built transporter object. */
     transport?: string | Transporter;
+    /** Default sender address. */
     from?: string;
+    /** Custom send function (bypasses nodemailer). */
     send?: (opts: MailOptions) => Promise<void>;
 }
+/** Mailer instance returned by {@link mailer}. */
 export interface Mailer {
+    /** Send an email. */
     send: (opts: MailOptions) => Promise<void>;
+    /** Close the nodemailer transport. */
     close: () => Promise<void>;
 }
+/**
+ * Create a mailer instance.
+ *
+ * ```ts
+ * import { mailer } from 'weifuwu'
+ *
+ * const email = mailer({ transport: 'smtp://user:pass@smtp.example.com' })
+ * await email.send({
+ *   to: 'user@example.com',
+ *   subject: 'Hello',
+ *   text: 'Hello from weifuwu!',
+ * })
+ * await email.close()
+ * ```
+ */
 export declare function mailer(options: MailerOptions): Mailer;

package/dist/permissions.d.ts

@@ -1,9 +1,11 @@
 import type { Sql } from './vendor.ts';
-import type { Middleware, Context } from './types.ts';
+import type { Middleware, Context, Handler } from './types.ts';
 declare module './types.ts' {
     interface Context {
-        roles: Set<string>;
-        permissions: Set<string>;
+        permissions: {
+            roles: Set<string>;
+            permissions: Set<string>;
+        };
     }
 }
 export interface PermissionsOptions {

package/dist/postgres/schema/columns.d.ts

@@ -1,43 +1,99 @@
 import { SQL } from './sql.ts';
+/** Reference to another table's column (foreign key). */
 export interface ColumnReference {
+    /** Referenced table name. */
     table: string;
+    /** Referenced column name (default: `'id'`). */
     column: string;
+    /** `ON DELETE` action (e.g. `'cascade'`, `'set null'`). */
     onDelete?: string;
 }
+/**
+ * Fluent column builder for DDL generation.
+ *
+ * ```ts
+ * text('name').notNull().unique()
+ * integer('user_id').references('users')
+ * timestamptz('created_at').default(sql`NOW()`)
+ * ```
+ */
 export declare class ColumnBuilder<T> {
+    /** Column name. */
     name: string;
+    /** SQL type string (e.g. `'TEXT'`, `'INTEGER'`). */
     sqlType: string;
+    /** Whether this column is PRIMARY KEY. */
     isPrimaryKey: boolean;
+    /** Whether this column allows NULL. */
     isNullable: boolean;
+    /** Whether this column has a UNIQUE constraint. */
     isUnique: boolean;
+    /** Whether the value is auto-generated (e.g. SERIAL, UUID defaults). */
     isAutoGenerate: boolean;
+    /** DEFAULT expression as a raw SQL string. */
     defaultExpr: string | null;
+    /** Foreign key reference, if any. */
     ref: ColumnReference | null;
     constructor(name: string, sqlType: string);
+    /** Mark as PRIMARY KEY (implies NOT NULL). */
     primaryKey(): this;
+    /** Add NOT NULL constraint. */
     notNull(): this;
+    /** Allow NULL values (default). */
     nullable(): this;
+    /** Set a DEFAULT value. Accepts raw SQL, string, number, or boolean. */
     default(expr: SQL | string | number | boolean): this;
+    /** Add UNIQUE constraint. */
     unique(): this;
+    /** Add FOREIGN KEY reference to another table. */
     references(table: string, column?: string, onDelete?: string): this;
 }
+/** Auto-incrementing integer primary key (`SERIAL`). */
 export declare function serial(name: string): ColumnBuilder<number>;
+/** UUID column. */
 export declare function uuid(name: string): ColumnBuilder<string>;
+/** TEXT column. */
 export declare function text(name: string): ColumnBuilder<string>;
+/** INTEGER column. */
 export declare function integer(name: string): ColumnBuilder<number>;
+/** BOOLEAN column (exported as `boolean`). */
 export declare function boolean_(name: string): ColumnBuilder<boolean>;
 export { boolean_ as boolean };
+/** TIMESTAMPTZ column (timestamp with time zone). */
 export declare function timestamptz(name: string): ColumnBuilder<string>;
+/** JSONB column (stores arbitrary JSON data). */
 export declare function jsonb<T = unknown>(name: string): ColumnBuilder<T>;
+/** TEXT[] column (PostgreSQL array of text). */
 export declare function textArray(name: string): ColumnBuilder<string[]>;
+/** Vector column for pgvector (embedding storage). Requires `dimensions`. */
 export declare function vector(name: string, dims: number): ColumnBuilder<number[]>;
 export interface PartitionByDef {
     type: 'RANGE' | 'LIST' | 'HASH';
     column: string;
 }
 export declare function partitionBy(type: 'range' | 'list' | 'hash', column: string): PartitionByDef;
+/**
+ * Create a pair of `created_at` / `updated_at` timestamp columns
+ * that default to `NOW()` and are NOT NULL.
+ *
+ * ```ts
+ * pgTable('users', {
+ *   id: serial('id').primaryKey(),
+ *   name: text('name'),
+ *   ...timestamps(),
+ * })
+ * ```
+ */
 export declare function timestamps(): {
     readonly created_at: ColumnBuilder<string>;
     readonly updated_at: ColumnBuilder<string>;
 };
+/**
+ * Convert a ColumnBuilder into a DDL column definition string.
+ *
+ * ```ts
+ * toDDL(text('name').notNull())
+ * // '"name" TEXT NOT NULL'
+ * ```
+ */
 export declare function toDDL(col: ColumnBuilder<unknown>): string;

package/dist/postgres/schema/sql.d.ts

@@ -1,7 +1,22 @@
+/**
+ * A parameterized SQL fragment with template strings and bound values.
+ * Used internally by the schema builder and where helpers.
+ */
 export declare class SQL {
+    /** Template string parts (interleaved with values). */
     strings: TemplateStringsArray;
+    /** Bound parameter values. */
     values: unknown[];
     constructor(strings: TemplateStringsArray, values: unknown[]);
+    /** Serialize to a raw SQL string (interpolating values inline for DDL use). */
     toSQL(): string;
 }
+/**
+ * Tagged template helper for creating parameterized SQL fragments.
+ *
+ * ```ts
+ * sql`NOW()`
+ * sql`${column} ILIKE ${'%' + search + '%'}`
+ * ```
+ */
 export declare function sql(strings: TemplateStringsArray, ...values: unknown[]): SQL;

package/dist/postgres/schema/table.d.ts

@@ -1,30 +1,69 @@
 import type { Sql } from '../../vendor.ts';
 import { ColumnBuilder, type PartitionByDef } from './columns.ts';
 import { SQL } from './sql.ts';
+/** Options for table index creation. */
 export interface IndexOptions {
+    /** Whether the index should be UNIQUE. */
     unique?: boolean;
+    /** Index type: btree (default), hnsw (pgvector), gin (JSONB). */
     type?: 'btree' | 'hnsw' | 'gin';
+    /** Create index in DESC order. */
     desc?: boolean;
+    /** Custom operator class (e.g. `vector_cosine_ops`). */
     operator?: string;
 }
+/** Options for CREATE TABLE. */
 export interface CreateOptions {
+    /** Partition by clause (RANGE, LIST, or HASH). */
     partitionBy?: PartitionByDef;
 }
+/** Options for find/read queries. */
 export interface FindOptions {
+    /** ORDER BY clause: `{ column: 'asc' | 'desc' }`. */
     orderBy?: Record<string, 'asc' | 'desc'>;
+    /** LIMIT. */
     limit?: number;
+    /** OFFSET. */
     offset?: number;
+    /** Columns to SELECT (default: all). */
     select?: string[];
+    /** Include soft-deleted rows (also sets `withDeleted` context). */
     withDeleted?: boolean;
 }
+/**
+ * Type-safe table schema + CRUD operations.
+ *
+ * Create an instance with {@link pgTable}, then call `.bind(sql)` to get a
+ * `BoundTable` for running queries.
+ *
+ * ```ts
+ * const users = pgTable('users', {
+ *   id: serial('id').primaryKey(),
+ *   name: text('name').notNull(),
+ *   email: text('email').unique(),
+ * })
+ *
+ * const db = users.bind(sql)
+ * await db.create()
+ * await db.insert({ name: 'Alice', email: 'a@b.com' })
+ * const row = await db.findBy({ email: 'a@b.com' })
+ * ```
+ */
 export declare class Table<R extends Record<string, unknown>> {
+    /** Database table name. */
     readonly tableName: string;
+    /** All column builders (order-preserving). */
     readonly columns: ColumnBuilder<unknown>[];
+    /** Column builders keyed by property name. */
     readonly builders: Record<string, ColumnBuilder<unknown>>;
     private colEntries;
     constructor(tableName: string, builders: Record<string, ColumnBuilder<unknown>>);
+    /** Check if the table has a column with the given DB name. */
     hasColumn(dbName: string): boolean;
-    /** Returns a BoundTable pre-bound to the given sql connection (no need to pass sql to every method). */
+    /**
+     * Bind this table schema to a SQL connection, returning a `BoundTable`
+     * that can run queries without passing `sql` to every call.
+     */
     bind(sql: Sql<{}>): BoundTable<R>;
     /** Returns the primary key column name (DB name), or 'id' as fallback. */
     private get pkColumn();
@@ -81,6 +120,20 @@ export declare class BoundTable<R extends Record<string, unknown>> {
     count(where?: Partial<R> | SQL | SQL[]): Promise<number>;
     withSql(sql: Sql<{}>): BoundTable<R>;
 }
+/**
+ * Define a type-safe table schema.
+ *
+ * ```ts
+ * const users = pgTable('users', {
+ *   id: serial('id').primaryKey(),
+ *   name: text('name').notNull(),
+ *   email: text('email').unique(),
+ * })
+ *
+ * // The generic type R preserves the column types:
+ * // Table<{ id: number; name: string; email: string }>
+ * ```
+ */
 export declare function pgTable<R extends Record<string, unknown>>(tableName: string, builders: {
     [K in keyof R]: ColumnBuilder<R[K]>;
 }): Table<R>;