@kequtech/tenon-orm 0.1.3 → 0.1.4

package/README.md

@@ -29,7 +29,7 @@ try {
   const email = 'reader@example.test';
   const user = await db.query(
     sql<{ id: number; email: string }>`
-      SELECT id, email FROM public."User" WHERE email = ${email}
+      SELECT id, email FROM public.users WHERE email = ${email}
     `,
     { returns: 'oneOrNone' },
   );

package/docs/agent-guide.md

@@ -9,6 +9,8 @@ This guide contains the setup and contracts needed for routine implementation; t
 
 1. Inspect the application's connection setup, migrations, generated types, query modules, and check
    commands. Reuse them. Do not replace a working migration runner just to use Tenon queries.
+   For new schemas, prefer plural `snake_case` table names and `snake_case` column names; preserve
+   existing schemas' names.
 2. Write straightforward SQL with explicit selected columns. Use separate complete queries when
    variants return different shapes. Introduce fragments only for actual reuse or variable
    composition.
@@ -47,12 +49,12 @@ or configure `search_path`; CLI `--namespace` does not change runtime query name
 
 ```ts
 import { sql, type QueryClient } from '@kequtech/tenon-orm';
-import type { User } from './generated-schema.js';
+import type { Rows } from './generated-schema.js';
 
-type Summary = Pick<User, 'id' | 'email'>;
+type Summary = Pick<Rows['users'], 'id' | 'email'>;
 
 function userById(client: QueryClient, { id }: { id: number }) {
-  return client.query(sql<Summary>`SELECT id, email FROM public."User" WHERE id = ${id}`, {
+  return client.query(sql<Summary>`SELECT id, email FROM public.users WHERE id = ${id}`, {
     returns: 'oneOrNone',
   });
 }
@@ -98,9 +100,9 @@ For example, share a search condition between a page and count query:
 
 ```ts
 const search = sql.fragment`active = ${true} AND email ILIKE ${pattern}`;
-const page = sql<Summary>`SELECT id, email FROM public."User"
+const page = sql<Summary>`SELECT id, email FROM public.users
   WHERE ${search} ORDER BY id LIMIT ${limit}`;
-const count = sql<{ count: string }>`SELECT count(*) AS count FROM public."User"
+const count = sql<{ count: string }>`SELECT count(*) AS count FROM public.users
   WHERE ${search}`;
 ```
 

package/docs/human-guide.md

@@ -36,8 +36,9 @@ application then closes that pool.
 
 ## Create a table
 
-If you already have a schema and migration runner, you can keep them. For a new schema, create a
-migration:
+If you already have a schema and migration runner, you can keep them. For new schemas, prefer plural
+`snake_case` table names and `snake_case` column names. Tenon preserves your schema's exact names.
+Create a migration:
 
 ```sh
 npx tenon new create_users
@@ -47,7 +48,7 @@ Fill the generated files:
 
 ```sql
 -- migrations/0001_create_users.up.sql
-CREATE TABLE public."User" (
+CREATE TABLE public.users (
   id integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
   email text NOT NULL UNIQUE,
   active boolean NOT NULL DEFAULT true
@@ -56,7 +57,7 @@ CREATE TABLE public."User" (
 
 ```sql
 -- migrations/0001_create_users.down.sql
-DROP TABLE public."User";
+DROP TABLE public.users;
 ```
 
 For development, add a script to `package.json` that applies migrations and updates generated types:
@@ -87,10 +88,10 @@ import { sql } from '@kequtech/tenon-orm';
 import { db } from './db.js';
 
 const email = 'reader@example.test';
-await db.query(sql`INSERT INTO public."User" (email) VALUES (${email})`);
+await db.query(sql`INSERT INTO public.users (email) VALUES (${email})`);
 const user = await db.query(
   sql<{ id: number; email: string }>`
-    SELECT id, email FROM public."User" WHERE email = ${email}
+    SELECT id, email FROM public.users WHERE email = ${email}
   `,
   { returns: 'oneOrNone' },
 );
@@ -107,8 +108,8 @@ These options do not change your SQL.
 Generated table types can help describe projections without repeating every field:
 
 ```ts
-import type { User } from './generated-schema.js';
-type UserSummary = Pick<User, 'id' | 'email'>;
+import type { Rows } from './generated-schema.js';
+type UserSummary = Pick<Rows['users'], 'id' | 'email'>;
 ```
 
 You can then write `sql<UserSummary>`. A table type describes the full table; a join or aggregate
@@ -123,15 +124,14 @@ supplied values easy to read:
 
 ```ts
 import { sql, type QueryClient } from '@kequtech/tenon-orm';
-import type { User } from './generated-schema.js';
+import type { Rows } from './generated-schema.js';
 
-type UserSummary = Pick<User, 'id' | 'email'>;
+type UserSummary = Pick<Rows['users'], 'id' | 'email'>;
 
 export function userByEmail(client: QueryClient, { email }: { email: string }) {
-  return client.query(
-    sql<UserSummary>`SELECT id, email FROM public."User" WHERE email = ${email}`,
-    { returns: 'oneOrNone' },
-  );
+  return client.query(sql<UserSummary>`SELECT id, email FROM public.users WHERE email = ${email}`, {
+    returns: 'oneOrNone',
+  });
 }
 
 const user = await userByEmail(db, { email: 'reader@example.test' });
@@ -147,7 +147,7 @@ await db.transaction(async (tx) => {
   const user = await userByEmail(tx, { email: 'reader@example.test' });
   if (!user) throw new Error('User not found');
 
-  await tx.query(sql`UPDATE public."User" SET active = false WHERE id = ${user.id}`, {
+  await tx.query(sql`UPDATE public.users SET active = false WHERE id = ${user.id}`, {
     affectedRows: { exact: 1 },
   });
 });
@@ -172,11 +172,11 @@ aligned, with `DEFAULT` for missing cells.
 ```ts
 import type { Rows } from './generated-schema.js';
 
-const input: Rows.Insert['User'] = { email: 'another@example.test' };
-await db.query(sql`INSERT INTO public."User" ${sql.insertValues(input, ['email'])}`);
+const input: Rows.Insert['users'] = { email: 'another@example.test' };
+await db.query(sql`INSERT INTO public.users ${sql.insertValues(input, ['email'])}`);
 
-const patch: Pick<Rows.Update['User'], 'active'> = { active: false };
-await db.query(sql`UPDATE public."User" SET ${sql.assignments(patch, ['active'])}
+const patch: Pick<Rows.Update['users'], 'active'> = { active: false };
+await db.query(sql`UPDATE public.users SET ${sql.assignments(patch, ['active'])}
   WHERE email = ${input.email}`);
 ```
 
@@ -227,7 +227,7 @@ For fixed conditions, write them directly:
 
 ```ts
 const users = await db.query(
-  sql<UserSummary>`SELECT id, email FROM public."User" WHERE active = ${true}`,
+  sql<UserSummary>`SELECT id, email FROM public.users WHERE active = ${true}`,
   { returns: 'many' },
 );
 ```
@@ -238,9 +238,9 @@ its count:
 
 ```ts
 const search = sql.fragment`active = ${true} AND email ILIKE ${pattern}`;
-const page = sql<UserSummary>`SELECT id, email FROM public."User"
+const page = sql<UserSummary>`SELECT id, email FROM public.users
   WHERE ${search} ORDER BY id LIMIT ${limit}`;
-const count = sql<{ count: string }>`SELECT count(*) AS count FROM public."User"
+const count = sql<{ count: string }>`SELECT count(*) AS count FROM public.users
   WHERE ${search}`;
 ```
 
@@ -258,7 +258,7 @@ for (const term of terms) {
   filters.push(sql.fragment`email ILIKE ${'%' + term + '%'}`);
 }
 
-const query = sql<UserSummary>`SELECT id, email FROM public."User"
+const query = sql<UserSummary>`SELECT id, email FROM public.users
   WHERE ${sql.join(filters, 'AND')} ORDER BY id`;
 ```
 

package/docs/reference.md

@@ -78,7 +78,7 @@ types from SQL context.
 Use an array parameter for a set of values:
 
 ```ts
-const query = sql<{ id: number }>`SELECT id FROM public."User"
+const query = sql<{ id: number }>`SELECT id FROM public.users
   WHERE id = ANY(${ids}::integer[])`;
 ```
 
@@ -114,7 +114,7 @@ const conditions = [sql.fragment`active = ${true}`];
 if (email !== undefined) conditions.push(sql.fragment`email = ${email}`);
 if (afterId !== undefined) conditions.push(sql.fragment`id > ${afterId}`);
 
-const query = sql<{ id: number }>`SELECT id FROM public."User"
+const query = sql<{ id: number }>`SELECT id FROM public.users
   WHERE ${sql.join(conditions, 'AND')} ORDER BY id`;
 ```
 
@@ -205,7 +205,7 @@ See the [mutation cookbook](mutations.md) for common patterns and
 ```ts
 await db.transaction(async (tx) => {
   const id = 42;
-  await tx.query(sql`UPDATE public."User" SET active = false WHERE id = ${id}`, {
+  await tx.query(sql`UPDATE public.users SET active = false WHERE id = ${id}`, {
     affectedRows: { exact: 1 },
   });
   // Use tx for every query that belongs to this transaction.
@@ -260,9 +260,18 @@ current database. It never rewrites the file. Pending migration files
 are a separate concern. The representation includes table columns, constraints, indexes, and
 referenced domains, not every PostgreSQL object.
 
-Generation reads a consistent snapshot of ordinary tables and partitioned roots. `Rows['User']`
-describes one returned row; the generated `User` alias means the same thing. Use `sql<User>` for a
-full row or `Pick<User, 'id' | 'email'>` for a projection. Table keys preserve exact SQL names;
+Generation reads a consistent snapshot of ordinary tables and partitioned roots. `Rows['users']`
+describes one returned row. Application type names can use PascalCase:
+
+```ts
+import type { Rows } from './generated-schema.js';
+
+type User = Rows['users'];
+type UserSummary = Pick<User, 'id' | 'email'>;
+```
+
+Use `sql<User>` for a full row or `sql<UserSummary>` for that projection. Generated table keys and
+named aliases preserve exact SQL names; the generated `users` alias also means `Rows['users']`.
 `type AuditRow = Rows['audit-log']` works for names that cannot be exported as identifiers.
 Views, foreign tables, and attached partitions use query-specific types. A missing namespace
 fails; an existing empty schema is valid.
@@ -417,7 +426,7 @@ It covers a separate SQL lint command, fix previews, and application refinements
 Write a query without a result annotation:
 
 ```ts
-const query = sql`SELECT id, email FROM public."User" WHERE id = ${id}`;
+const query = sql`SELECT id, email FROM public.users WHERE id = ${id}`;
 ```
 
 Run `npm run lint:fix`. SafeQL can write `sql<{ id: number; email: string }>` using the connected
@@ -540,7 +549,7 @@ safeql.configs.connections({
   plugins: [safeqlPlugin],
   targets: [{ tag: 'sql' }],
   overrides: {
-    columns: { 'User.tags': 'PgArray<string>', 'User.amounts': 'PgArray<number>' },
+    columns: { 'users.tags': 'PgArray<string>', 'users.amounts': 'PgArray<number>' },
   },
 });
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kequtech/tenon-orm",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "license": "ISC",
   "type": "module",
   "description": "A PostgreSQL ORM designed for coding agents, with explicit SQL, typed queries, and migrations",