@vanit-co/sql-ts 0.0.1 → 0.0.2

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']
 ```
 
 ---
@@ -335,7 +387,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 +395,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 +403,7 @@ const buildPostsQuery = ({ userId, titleLike }: Filters) => {
   ]
 
   return reduce(
-    (acc: Fragment, clause: Fragment) => concat(clause)(acc),
+    (acc, clause) => concat(clause)(acc),
     empty,
     clauses
   )
@@ -407,7 +459,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 +467,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;
@@ -53,6 +52,7 @@ declare const select: (strings: TemplateStringsArray, ...binds: Array<any>) => R
 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;
 

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;
@@ -118,6 +117,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]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanit-co/sql-ts",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "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",