@vanit-co/sql-ts 0.0.1 → 0.2.0

package/README.md

@@ -4,6 +4,20 @@ A TypeScript SQL query builder using tagged template literals. Write plain SQL w
 
 Supports **MySQL** (`?` placeholders, `` ` `` backtick identifiers) and **PostgreSQL** (`$n` placeholders, `"` double-quote identifiers) out of the box.
 
+## Why this library?
+
+Writing raw SQL in TypeScript runs into a set of recurring friction points that this library addresses directly:
+
+- **Automatic identifier quoting** — table and column names are interpolated as properly quoted identifiers (`` `name` `` for MySQL, `"name"` for PostgreSQL), never as bind parameters. No manual quoting, no dialect-specific escaping scattered across your codebase.
+
+- **Table alias and qualified column references** — the `select` tag (and its aliases `join`, `where`) automatically expands schema tables as `"table" "alias"` and columns as `"alias"."column"`, so JOIN-heavy queries stay unambiguous without hand-writing every qualified reference.
+
+- **Column alias expansion** — `selectAs` goes further, rendering each column as `"alias"."column" as "alias_column"`. When querying multiple joined tables, result-set keys no longer collide.
+
+- **`concat` and `empty` as a monoid** — every tagged template and statement builder returns a `Fragment`. `concat` joins two fragments into one, and `empty` is the identity element. This lets you accumulate query fragments conditionally with `reduce`, compose them with `pipe`, or chain them with `.append` — treating query construction as plain data transformation.
+
+- **`all` and `pick` helpers** — expand an entire table's columns or a chosen subset into a comma-separated list inside any tag, so `SELECT ${all(users, posts)}` replaces repetitive column lists without losing type safety.
+
 ## Installation
 
 ```sh
@@ -12,19 +26,57 @@ npm install @vanit-co/sql-ts
 
 ## Quick example
 
+**sql** tagged template literal takes care of quoting the identifiers (tables and columns) with the proper quotes `` ` `` for MySQL and `"` for PostgreSQL.
+
 ```ts
-import { schema, select, where, all } from '@vanit-co/sql-ts'
+import { schema, sql, all } from '@vanit-co/sql-ts'
 
 const users = schema({ table: 'users', columns: ['id', 'email'] })
 
-const query = select`SELECT ${all(users)} FROM ${users} WHERE ${users.id} = ${42}`
+const query = sql`SELECT ${all(users)} FROM ${users} WHERE ${users.id} = ${42}`
 
 // PostgreSQL
-console.log(query.text)   // SELECT "users"."id" ,"users"."email" FROM "users" "users" WHERE "users"."id" = $1
-console.log(query.values) // [42]
+console.log(query.text)   // SELECT "id" ,"email" FROM "users" WHERE "id" = $1
 
 // MySQL
-console.log(query.sql)    // SELECT `users`.`id` ,`users`.`email` FROM `users` `users` WHERE `users`.`id` = ?
+console.log(query.sql)    // SELECT `id` ,`email` FROM `users` WHERE `id` = ?
+
+console.log(query.values) // [42]
+```
+
+## Full query example
+
+**select** tagged template literal works like **sql** but automatically adds table aliases and column prefixes. The other tagged template literals **join** and **where** are just aliases to **select** with the aim of maintaining semantics. The **selectAs** tagged template literal besides the column prefixes will also add the column alias using the format `$prefix_$columnName`.
+
+```ts
+import { schema, select, selectAs, join, where, all, insert, update, empty } from '@vanit-co/sql-ts'
+
+const users = schema({ table: 'users', columns: ['id', 'email'], alias: 'u' })
+const posts = schema({ table: 'posts', columns: ['id', 'user_id', 'title'], alias: 'p' })
+
+const id = 42
+
+// SELECT with JOIN
+const query = selectAs`SELECT ${all(users, posts)} FROM ${posts}`
+  .append(join`JOIN ${users} ON ${posts.user_id} = ${users.id}`)
+  .append(id ? where`WHERE ${users.id} = ${42}` : empty)
+
+query.text
+// SELECT "u"."id" as "u_id" ,"u"."email" as "u_email" ,"p"."id" as "p_id" ,"p"."user_id" as "p_user_id" ,"p"."title" as "p_title"
+// FROM "posts" "p"
+// JOIN "users" "u" ON "p"."user_id" = "u"."id"
+// WHERE "u"."id" = $1
+query.values // [42]
+
+// INSERT
+const ins = insert(users, { id: 1, email: 'alice@example.com' })
+ins.text    // insert into "users" ("id" ,"email") values ($1 ,$2)
+ins.values  // [1, 'alice@example.com']
+
+// UPDATE
+const upd = update(users, { email: 'new@example.com' })
+upd.text    // update "users" set "email" = $1
+upd.values  // ['new@example.com']
 ```
 
 ---
@@ -53,6 +105,34 @@ const u = schema({ table: 'users', columns: ['id', 'email'], alias: 'u' })
 
 After calling `schema`, the returned object has a typed property for each column (`users.id`, `users.email`, etc.).
 
+### `as(column)`
+
+Returns the aliased column name as a plain string — the same `prefix_name` string that `selectAs` writes into the SQL `AS` clause. Use this to read a column out of query results by its aliased key without repeating the string manually.
+
+```ts
+import { schema, as, selectAs, all } from '@vanit-co/sql-ts'
+
+const users = schema({ table: 'users', columns: ['id', 'email'] })
+const u = schema({ table: 'users', columns: ['id', 'email'], alias: 'u' })
+
+as(users.id)     // 'users_id'
+as(users.email)  // 'users_email'
+
+as(u.id)         // 'u_id'
+as(u.email)      // 'u_email'
+```
+
+This is particularly useful when mapping over result rows:
+
+```ts
+const rows = await client.query(selectAs`SELECT ${all(users)} FROM ${users}`)
+
+rows.map(row => ({
+  id:    row[as(users.id)],    // row['users_id']
+  email: row[as(users.email)], // row['users_email']
+}))
+```
+
 ---
 
 ### Result object
@@ -335,7 +415,7 @@ An empty fragment. Acts as the identity element for `concat` — useful as the s
 
 ```ts
 import { pipe, reduce } from 'ramda'
-import { schema, select, join, where, concat, empty, all, Fragment } from '@vanit-co/sql-ts'
+import { schema, select, join, where, concat, empty, all } from '@vanit-co/sql-ts'
 
 const users = schema({ table: 'users', columns: ['id', 'email'], alias: 'u' })
 const posts = schema({ table: 'posts', columns: ['id', 'user_id', 'title'], alias: 'p' })
@@ -343,7 +423,7 @@ const posts = schema({ table: 'posts', columns: ['id', 'user_id', 'title'], alia
 type Filters = { userId?: number; titleLike?: string }
 
 const buildPostsQuery = ({ userId, titleLike }: Filters) => {
-  const clauses: Fragment[] = [
+  const clauses = [
     select`SELECT ${all(users, posts)} FROM ${posts}`,
     join`  JOIN ${users} ON ${posts.user_id} = ${users.id}`,
     userId    ? where` WHERE ${users.id} = ${userId}`          : empty,
@@ -351,7 +431,7 @@ const buildPostsQuery = ({ userId, titleLike }: Filters) => {
   ]
 
   return reduce(
-    (acc: Fragment, clause: Fragment) => concat(clause)(acc),
+    (acc, clause) => concat(clause)(acc),
     empty,
     clauses
   )
@@ -407,7 +487,7 @@ Attach a name to a `Result` for use with named prepared statements (e.g., `pg`'s
 ```ts
 import { sql, preparedStatementName } from '@vanit-co/sql-ts'
 
-const q = sql`SELECT * FROM users WHERE id = ${1}`
+const q = sql`SELECT * FROM ${users} WHERE id = ${1}`
 const named = preparedStatementName(q, 'get-user-by-id')
 
 named.name   // 'get-user-by-id'
@@ -415,46 +495,13 @@ named.text   // SELECT * FROM users WHERE id = $1
 named.values // [1]
 
 // Pass to pg:
-await client.query({ name: named.name, text: named.text, values: named.values })
+await client.query(named)
 ```
 
 `preparedStatementName` does not mutate the original result — it returns a new object.
 
 ---
 
-## Full query example
-
-```ts
-import { schema, select, selectAs, join, where, all, insert, update, concat } from '@vanit-co/sql-ts'
-
-const users = schema({ table: 'users', columns: ['id', 'email'], alias: 'u' })
-const posts = schema({ table: 'posts', columns: ['id', 'user_id', 'title'], alias: 'p' })
-
-// SELECT with JOIN
-const query = selectAs`SELECT ${all(users, posts)} FROM ${posts}`
-  .append(join`JOIN ${users} ON ${posts.user_id} = ${users.id}`)
-  .append(where`WHERE ${users.id} = ${42}`)
-
-query.text
-// SELECT "u"."id" as "u_id" ,"u"."email" as "u_email" ,"p"."id" as "p_id" ,"p"."user_id" as "p_user_id" ,"p"."title" as "p_title"
-// FROM "posts" "p"
-// JOIN "users" "u" ON "p"."user_id" = "u"."id"
-// WHERE "u"."id" = $1
-query.values // [42]
-
-// INSERT
-const ins = insert(users, { id: 1, email: 'alice@example.com' })
-ins.text    // insert into "users" ("id" ,"email") values ($1 ,$2)
-ins.values  // [1, 'alice@example.com']
-
-// UPDATE
-const upd = update(users, { email: 'new@example.com' })
-upd.text    // update "users" set "email" = $1
-upd.values  // ['new@example.com']
-```
-
----
-
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,18 +1,7 @@
-type Result = {
-    append: (s: Fragment) => Fragment;
-    name?: string;
-    sql: string;
-    text: string;
-    values: Array<any>;
-} & Fragment;
-declare const preparedStatementName: (r: Result, n: string) => Result;
-
 type Fragment = {
     readonly strings: ReadonlyArray<string>;
     readonly binds: ReadonlyArray<unknown>;
 };
-declare const concat: (right: Fragment) => (left: Fragment) => Result;
-declare const empty: Fragment;
 
 type MysqlResult = {
     readonly sql: string;
@@ -25,6 +14,16 @@ type PostgresResult = {
 declare const toMysql: (s: Fragment) => MysqlResult;
 declare const toPostgres: (s: Fragment) => PostgresResult;
 
+type Result = {
+    append: (s: Fragment) => Result;
+    name?: string;
+    sql: string;
+    text: string;
+    values: Array<any>;
+} & Fragment;
+declare const preparedStatementName: (r: Result, n: string) => Result;
+declare const concat: (right: Fragment) => (left: Fragment) => Result;
+
 type Table = {
     readonly name: string;
     readonly alias: string;
@@ -47,12 +46,14 @@ type Params<T extends string> = {
     readonly alias?: string;
 };
 declare const schema: <T extends string>({ table, columns, alias }: Params<T>) => SchemaTable<T>;
+declare const as: (col: { [K in symbol]: Column; }) => string;
 
 declare const sql: (strings: TemplateStringsArray, ...binds: Array<any>) => Result;
 declare const select: (strings: TemplateStringsArray, ...binds: Array<any>) => Result;
 declare const selectAs: (strings: TemplateStringsArray, ...binds: Array<any>) => Result;
 declare const join: (strings: TemplateStringsArray, ...binds: Array<any>) => Result;
 declare const where: (strings: TemplateStringsArray, ...binds: Array<any>) => Result;
+declare const empty: Result;
 declare const insert: <T extends string>(table: SchemaTable<T>, ...colsVals: Array<{ [K in T]?: any; }>) => Result;
 declare const update: <T extends string>(table: SchemaTable<T>, colsVals: { [K in T]?: any; }) => Result;
 
@@ -68,4 +69,4 @@ declare const pick: (...columns: Array<{
 }>) => Value;
 declare const raw: (content: string) => Value;
 
-export { all, concat, empty, insert, join as j, join, pick, preparedStatementName, raw, select as s, selectAs as sa, schema, select, selectAs, sql, toMysql, toPostgres, update, where as w, where };
+export { all, as, concat, empty, insert, join as j, join, pick, preparedStatementName, raw, select as s, selectAs as sa, schema, select, selectAs, sql, toMysql, toPostgres, update, where as w, where };

package/dist/index.js

@@ -15,32 +15,11 @@ const zipLongest = (l1, l2) => {
     return Array.from({ length: maxLength }, (_, i) => [l1[i], l2[i]]);
 };
 
-const preparedStatementName = (r, n) => ({ ...r, name: n });
-const result = (s) => ({
-    ...s,
-    append: (x) => concat(x)(s),
-    get sql() {
-        return toMysql(s).sql;
-    },
-    get text() {
-        return toPostgres(s).text;
-    },
-    get values() {
-        return s.binds.filter((x) => !(x[SYM_RAW] || x[SYM_IDENTIFIER]));
-    }
-});
-
-const concat = (right) => (left) => {
-    const lastLeft = left.strings[left.strings.length - 1] ?? '';
-    const firstRight = right.strings[0] ?? '';
-    return result(fragment([...left.strings.slice(0, -1), lastLeft + firstRight, ...right.strings.slice(1)], [...left.binds, ...right.binds]));
-};
-const fragment = (strings, binds) => {
+const fragment = (strings, binds = []) => {
     if (strings.length !== binds.length + 1)
         throw new Error(`Malformed fragment: ${strings.length} strings for ${binds.length} values`);
     return Object.freeze({ strings, binds });
 };
-const empty = fragment([''], []);
 const stringfyIdentifierAndRaw = (quote = '') => (s) => {
     const fn = ([strings, binds, merge], [ss, bs]) => {
         if (bs && bs[SYM_RAW]) {
@@ -72,6 +51,26 @@ const toPostgres = (s) => {
     };
 };
 
+const preparedStatementName = (r, n) => ({ ...r, name: n });
+const concat = (right) => (left) => {
+    const lastLeft = left.strings[left.strings.length - 1] ?? '';
+    const firstRight = right.strings[0] ?? '';
+    return result(fragment([...left.strings.slice(0, -1), lastLeft + firstRight, ...right.strings.slice(1)], [...left.binds, ...right.binds]));
+};
+const result = (s) => ({
+    ...s,
+    append: (x) => concat(x)(s),
+    get sql() {
+        return toMysql(s).sql;
+    },
+    get text() {
+        return toPostgres(s).text;
+    },
+    get values() {
+        return s.binds.filter((x) => !(x[SYM_RAW] || x[SYM_IDENTIFIER]));
+    }
+});
+
 const makeColumns = (prefix, cols) => cols.reduce((a, key) => ({ ...a, [key]: { [SYM_COLUMN]: { name: key, prefix } } }), {});
 const schema = ({ table, columns, alias }) => {
     const resolvedAlias = alias ?? table;
@@ -80,6 +79,10 @@ const schema = ({ table, columns, alias }) => {
         ...makeColumns(resolvedAlias, columns)
     };
 };
+const as = (col) => {
+    const c = col[SYM_COLUMN];
+    return c.prefix + '_' + c.name;
+};
 
 const identifier = (content) => ({ [SYM_IDENTIFIER]: true, content });
 
@@ -118,6 +121,7 @@ const select = buildTag(prefix);
 const selectAs = buildTag(alias);
 const join = select;
 const where = select;
+const empty = sql ``;
 const insert = (table, ...colsVals) => {
     const tableName = table[SYM_TABLE].name;
     const columns = Object.keys(colsVals[0]);
@@ -150,6 +154,7 @@ const raw = (content) => ({
 });
 
 exports.all = all;
+exports.as = as;
 exports.concat = concat;
 exports.empty = empty;
 exports.insert = insert;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanit-co/sql-ts",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "A TypeScript SQL query builder using tagged template literals. Write plain SQL with safe, automatic parameter binding and properly quoted identifiers. No DSL to learn, no magic, no ORM.",
   "type": "module",
   "main": "./dist/index.js",