arn-db 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,266 @@
-# Temporary Holding Version
+# arn-db
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Supabase-style query builder for Node.js. It talks to a Go query API
+(`/v2/raw`), which talks to Postgres. It replaces arn-knexjs.
+
+```
+Node app (arn-db) ──HTTP/JSON──▶ your-api.example.com/v2/raw (Go) ──▶ Postgres
+```
+
+Server-side only: every request is a POST with an `apikey` header, and the API
+refuses browser requests (any request with an `Origin` header) and sends no CORS
+headers. Each key may be limited to a list of tables.
+
+**New here? Read [GUIDE.md](GUIDE.md):** recipes for selecting, relations,
+searching across tables, ordering/random, jsonb changes, counts, upsert and
+transactions, each with its real output.
+
+## Install
+
+```bash
+npm install arn-db
+```
+
+Set the API address and the app's key (in `.env` or the container env):
+
+```
+ARN_DB_URL=https://your-api.example.com/v2/raw
+ARN_DB_KEY=<your API key>
+```
+
+```js
+import { db } from 'arn-db'          // or: const { db } = require('arn-db')
+
+const { data, error } = await db.from('users').select().eq('id', 1).single()
+```
+
+That's all: `db` reads the two variables on its first query. If they aren't set,
+it loads `./.env` first (Node 20.12+), as arn-knexjs did with dotenv. ESM, CommonJS and
+TypeScript types are included.
+
+## Quick tour
+
+Import the ready `db` everywhere: `db.from()`, `db.transaction()`, `db.ops.*`,
+`db.rel.*`, `db.raw()`. Inside transactions the same helpers are on `tx` (`tx.ops.*`,
+`tx.rel.*`, `tx.raw()`, `tx.ref()`). For another key or options, make your own client with
+`createClient(url, key, options)`.
+
+```ts
+import { db } from 'arn-db'
+
+// all columns: select() or select('*'); with related rows: select('*, posts!user_id(*)')
+const { data, error } = await db.from('users').select()
+
+// filters, several orders, random (after other orders it only shuffles ties)
+await db.from('users').select('id, name').eq('active', true)
+  .order('vip', { ascending: false }).order('age', { ascending: false }).random().limit(5)
+
+// stable random pages: same seed, same order, no repeats across range() pages
+await db.from('posts').select('*').random({ seed: sessionId }).range(10, 19)
+
+// one row -> object or null; limit(1) -> always an array
+await db.from('users').select().eq('id', id).single()       // { ... } or null
+await db.from('users').select().limit(1)                    // [{ ... }] or []
+
+// writes: returning() is always an array, like Postgres RETURNING ('*' or columns)
+await db.from('users').insert({ name, email }).returning('id') // [{ id }]
+await db.from('users').update({ active: false }).eq('age', 30) // data: null, count: rows changed
+
+// OR / NOT, nested as deep as you need (chained filters are AND)
+await db.from('users').select('name').or((q) => q.gt('age', 60).and((q) => q.eq('active', false).lt('age', 20)))
+await db.from('users').select('name').not('meta->>city', 'eq', 'Dhaka')
+
+// JSON paths, casts, contains
+await db.from('users').select('name, city:meta->>city').gte('meta->>score::int', 90)
+await db.from('users').select('*').contains('meta', { vip: true })
+
+// relations: key = table name, or the alias you give it
+await db.from('posts').select('title, author:users!user_id(name), comments(body), labels(name)')
+await db.from('users').select('name, posts!user_id!inner(title)').eq('posts.published', false)
+await db.from('labels').select('name, posts(title)').random({ referencedTable: 'posts' }).limit(3, { referencedTable: 'posts' })
+
+// read replica (when the server has one; otherwise the primary answers)
+await db.from('posts').select('title').replica()
+const reads = createClient(url, key, { readFrom: 'replica' })   // import { createClient }; all reads; .primary() to opt out
+
+// atomic updates
+await db.from('users').update({ scores: db.ops.append(4), age: db.ops.increment() }).eq('id', id)
+await db.from('users').update({ meta: db.ops.append('x').at('address', 'lines') }).eq('id', id)
+```
+
+Errors never throw: every call (and every transaction) resolves to
+`{ data, error, count, status }`, like Supabase. Only setup mistakes throw:
+`createClient()` without an API key or fetch, `db.raw()` without a SQL string,
+and `db`'s first query when `ARN_DB_URL` / `ARN_DB_KEY` is missing.
+
+## Searching arrays (jsonb arrays and Postgres arrays)
+
+For a column holding `["one", "two"]`:
+
+```ts
+.overlaps('tags', ['one', 'three'])            // has ANY of them      -> matches
+.contains('tags', ['one', 'two'])              // has ALL of them      -> matches
+.containedBy('tags', ['one', 'two', 'three'])  // has NOTHING else     -> matches
+.eq('tags', ['one', 'two'])                    // exactly, same order  -> matches
+.overlaps('meta->tags', ['red'])               // array inside a jsonb object
+```
+
+These work on `jsonb` / `json` arrays (any element type, including objects) and on
+Postgres arrays like `text[]`. A value that is not an array simply doesn't match.
+
+## Counts
+
+```ts
+const { data: total } = await db.from('users').count()                      // 100
+const { data: active } = await db.from('users').eq('active', true).count()  // 75
+
+// Supabase form: count without rows (data is null)
+const { count } = await db.from('users').select('*', { count: 'exact', head: true }).eq('active', false)
+
+// rows + total, for "page 1 of N"
+const { data, count: all } = await db.from('posts').select('*', { count: 'exact' }).range(0, 9)
+
+// per related row (Supabase shape)
+await db.from('users').select('name, posts!user_id(count)')
+// [{ name: 'user_5', posts: [{ count: 2 }] }, ...]   many-to-one gives { count: n }
+```
+
+Counts work in transactions too: `{ n: tx.from('posts').eq('user_id', tx.ref('user.id')).count() }`.
+
+## Upsert
+
+```ts
+// insert, or update the existing row with the same email
+await db.from('users').upsert({ email, name }, { onConflict: 'email' }).returning()
+
+// find-or-create: insert, or return the existing row unchanged
+const { data: user } = await db.from('users')
+  .upsert({ email, name }, { onConflict: 'email', ignoreDuplicates: true })
+  .returning('id')
+user[0].id // returning() is always an array
+```
+
+- `onConflict` columns need a unique constraint (default: the primary key).
+- `ignoreDuplicates: true` still returns the existing row (Supabase returns
+  nothing there), so a transaction step can `tx.ref()` it.
+- Safe under concurrency: many requests creating the same row at once all get
+  the same row, with no duplicate and no error.
+- One row or many (up to 5,000). `merge: { total: 'add', email: 'set', hits: ops.increment(1) }`
+  changes only those columns of an existing row; see GUIDE.md.
+
+## Writes across related tables (all or nothing)
+
+Put `rel.*` under the related table's name (add `!fk_column` when the table has
+several FKs to it, e.g. `'users!user_id'`). The whole `insert()`/`update()` runs
+in one database transaction: if any part fails, nothing is saved.
+
+```ts
+await db.from('posts').insert({
+  title: 'Hello',
+  user_id: userId,
+  comments: db.rel.create([{ body: 'first', author_id: userId }]), // post_id filled in
+  labels: db.rel.connect([labelId]),                               // post_labels row added
+}).select('*, comments(*), labels(*)')
+
+await db.from('posts').update({
+  title: 'New title',
+  labels: db.rel.set([labelA, labelB]),                       // exactly these links
+  comments: db.rel.update({ id: commentId }, { body: 'edited' }),
+}).eq('id', postId)
+```
+
+| | one-to-many (`posts → comments`) | many-to-many (`posts ↔ labels`) | many-to-one (`posts → users!user_id`) |
+|---|---|---|---|
+| `db.rel.create(rows)` | insert children | insert targets + link | insert target first, set the FK |
+| `db.rel.upsert(row, { onConflict })` | insert or update a child | upsert target + link | upsert target, set the FK |
+| `db.rel.connectOrCreate(row, { onConflict })` | find or create a child, move it here | find or create target + link | find or create target, set the FK |
+| `db.rel.connect(keys)` | move children here | link | set the FK |
+| `db.rel.disconnect(keys)` | set child FK to null | unlink | set the FK to null |
+| `db.rel.set(keys)` | exactly these children | exactly these links | — |
+| `db.rel.update(match, values)` | update matching children | update matching linked rows | — |
+| `db.rel.delete(match?)` | delete matching children | delete matching linked rows | — |
+
+Created rows may contain `rel.*` themselves (any depth). `connect` fails if a key
+does not exist. `returning()` on a nested write needs a single-column primary key.
+
+## Transactions with several steps
+
+Return an object: keys name the steps, run top to bottom, and `data` has the
+same keys (typed per step).
+
+```ts
+const { data, error } = await db.transaction((tx) => ({
+  user: tx.from('users').upsert({ email, name }, { onConflict: 'email', ignoreDuplicates: true }).returning('id'),
+  post: tx.from('posts').upsert({ user_id: tx.ref('user.id'), title }, { onConflict: 'user_id,title', ignoreDuplicates: true }).returning('id'),
+  link: tx.from('post_labels').upsert({ post_id: tx.ref('post.id'), label_id }, { ignoreDuplicates: true }),
+}))
+data.user[0].id // found or created
+data.link       // null: no returning()
+error?.stepName // which step failed; everything is rolled back
+```
+
+Or return an array and name steps with `.as()`; `data` is then an array.
+
+```ts
+await db.transaction((tx) => [
+  tx.from('posts').insert({ title, user_id }).returning('id').as('post'),
+  tx.from('post_labels').insert({ post_id: tx.ref('post.id'), label_id }),
+])
+```
+
+- Steps can be any select / insert / upsert / update / delete, with `ops.*` and `rel.*`.
+- Don't `await` steps inside the callback; return them.
+- `tx.ref('user.id')` reads an earlier step's row (in values or filters). If it
+  returned an array, pick one: `tx.ref('posts.0.id')`.
+- Step names: words without dots. Number-like keys (`'1'`) are rejected because
+  JavaScript would reorder them.
+
+## Raw SQL fragments
+
+For the bits the builder has no method for, `db.raw(sql, bindings?)` (also
+`import { raw }` and `tx.raw`) adds one SQL expression to the query the builder
+makes, like knex's `whereRaw` / `orderByRaw` / `knex.raw`. It is a fragment,
+never a whole statement.
+
+```ts
+// filters: AND (<fragment>), or one member of an or() group
+await db.from('users').select('id').where(db.raw('lower(trim(email)) = any(?)', [emails]))
+await db.from('accounts').select().or((q) => q.where(db.raw('sent_per_hour < limit_per_hour')).is('limit_per_hour', null))
+
+// order, computed select columns (.as() is required), having
+await db.from('accounts').select().order(db.raw("coalesce(last_read_time, '1970-01-01')"), { ascending: true })
+await db.from('posts').select('id, title', db.raw('char_length(title)').as('title_len'))
+await db.from('posts').select('user_id, n:count()').groupBy('user_id').having(db.raw('count(*) >= ?', [2]))
+
+// values in insert / update / upsert rows, and in upsert merge (excluded.col = incoming value)
+await db.from('accounts').update({ sent_total: db.raw('sent_total + ?', [1]) }).eq('id', id)
+await db.from('accounts').upsert(rows, {
+  onConflict: 'email',
+  merge: { total: db.raw('CASE WHEN excluded.total IS NULL THEN accounts.total ELSE excluded.total END') },
+})
+```
+
+- Each `?` is a binding, sent as a query parameter (never pasted into the SQL).
+  Their number must match `bindings`. An array binding is a Postgres array
+  (`= any(?)`), an object is jsonb (`?::jsonb`). `?` inside `'quoted text'` is
+  not a binding.
+- `\?` (in a JS string: `'\\?'`) is a literal `?`, for the jsonb `?` operator:
+  `db.raw('meta \\? ?', ['vip'])`.
+- A fragment sees the main table's columns, plain or qualified with the table
+  name (`accounts.total`); not related tables.
+- The API key must be allowed to use raw fragments; otherwise the request gets
+  403 `RAW_NOT_ALLOWED`.
+- The server rejects (400 `RAW_FRAGMENT`): `;`, `--` and `/* */` comments,
+  dollar quoting, statement keywords (`select`, `insert`, `update`, `delete`,
+  `with`, `union`, `into`, `drop`, `alter`, `create`, `truncate`, …) outside
+  quoted text, fragments over 2,000 characters and more than 100 bindings.
+
+| knex | arn-db |
+|---|---|
+| `whereRaw(sql, b)` / `andWhereRaw(sql, b)` | `.where(db.raw(sql, b))` |
+| `orWhereRaw(sql, b)` | `.or((q) => q.where(db.raw(sql, b)).eq(...))` |
+| `orderByRaw(sql, b)` | `.order(db.raw(sql, b), { ascending })` |
+| `select('id', knex.raw('… as x'))` | `.select('id', db.raw('…').as('x'))` |
+| `{ col: knex.raw('col + ?', [1]) }` value | `{ col: db.raw('col + ?', [1]) }` |
+| `merge({ col: knex.raw(...) })` | `upsert(rows, { merge: { col: db.raw(...) } })` |
+| `havingRaw(sql, b)` | `.having(db.raw(sql, b))` |