@rip-lang/db 1.1.8 → 1.2.0

package/README.md

@@ -108,6 +108,178 @@ Response format:
 | `/tables` | GET | List all tables |
 | `/schema/:table` | GET | Table schema |
 
+## Database Client
+
+Rip DB includes an ActiveRecord-style database client for use in Rip
+applications. Import it from `@rip-lang/db/client` — it talks to a running
+`rip-db` server over HTTP with parameterized queries.
+
+```rip
+import { connect, query, findOne, findAll, Model } from '@rip-lang/db/client'
+
+connect 'http://localhost:4213'   # optional — defaults to DB_URL env or localhost:4213
+```
+
+### Low-Level Queries
+
+Every query uses parameterized placeholders (`$1`, `$2`, ...) to prevent SQL
+injection. Results are automatically materialized into plain objects.
+
+```rip
+# Raw result (meta + data arrays)
+result = query! "SELECT * FROM users WHERE active = $1", [true]
+
+# Single object or null
+user = findOne! "SELECT * FROM users WHERE id = $1", [42]
+
+# Array of objects
+users = findAll! "SELECT * FROM users WHERE role = $1", ['admin']
+```
+
+### Model Factory
+
+Create a Model for any table to get a full set of CRUD operations and a
+chainable query builder.
+
+```rip
+User = Model 'users'
+```
+
+#### Find & Count
+
+```rip
+user  = User.find! 42           # SELECT * FROM "users" WHERE id = $1
+count = User.count!              # SELECT COUNT(*) ...
+users = User.all!                # SELECT * FROM "users"
+users = User.all! 10             # SELECT * FROM "users" LIMIT 10
+```
+
+#### Chainable Queries
+
+All query methods return a new builder — chains are immutable and reusable.
+
+```rip
+User.where(active: true).order('name').limit(10).all!
+User.where(active: true).offset(20).limit(10).all!
+User.where('age > $1', [21]).all!
+User.select('id, name').where(role: 'admin').first!
+```
+
+#### Where, Or, Not
+
+```rip
+# Object-style (null-aware — generates IS NULL / IS NOT NULL)
+User.where(role: 'admin').all!
+User.where(deleted_at: null).all!          # WHERE "deleted_at" IS NULL
+
+# String-style with params
+User.where('age > $1', [21]).all!
+
+# OR conditions
+User.where(active: true).or(role: 'admin').all!
+User.where(active: true).or('role = $1', ['admin']).all!
+
+# NOT conditions
+User.where(active: true).not(role: 'banned').all!
+User.not(deleted_at: null).all!            # WHERE "deleted_at" IS NOT NULL
+```
+
+#### Group & Having
+
+```rip
+User.group('role').select('role, count(*) as n').all!
+User.group('role').having('count(*) > $1', [5]).select('role, count(*) as n').all!
+```
+
+#### Insert, Update, Upsert, Destroy
+
+All mutations return the affected row(s) via `RETURNING *`.
+
+```rip
+# Insert — returns the new record
+user = User.insert! { first_name: 'Alice', email: 'alice@example.com' }
+
+# Update by id — returns the updated record
+user = User.update! 42, { email: 'newemail@example.com' }
+
+# Upsert — insert or update on conflict
+user = User.upsert! { email: 'alice@example.com', name: 'Alice' }, on: 'email'
+
+# Destroy by id — returns the deleted record
+user = User.destroy! 42
+```
+
+#### Bulk Update & Destroy via Query Builder
+
+Chain `.where()` with `.update!` or `.destroy!` for bulk operations.
+
+```rip
+# Update all matching rows
+User.where(role: 'guest').update! { role: 'member' }
+
+# Delete all matching rows
+User.where(active: false).destroy!
+```
+
+#### Raw Parameterized Queries
+
+For anything the builder doesn't cover, drop down to raw SQL.
+
+```rip
+users = User.query! "SELECT * FROM users WHERE dob > $1", ['2000-01-01']
+```
+
+#### Cross-Database Queries
+
+Pass a database name to query attached DuckDB databases.
+
+```rip
+Archive = Model 'orders', 'archive_db'
+order = Archive.find! 99    # SELECT * FROM "archive_db"."orders" WHERE id = $1
+```
+
+### Query Builder Reference
+
+| Method | Description |
+|--------|-------------|
+| `.where(obj)` | AND conditions from object (`null` becomes `IS NULL`) |
+| `.where(sql, params)` | AND with raw SQL fragment |
+| `.or(obj)` | OR conditions from object |
+| `.or(sql, params)` | OR with raw SQL fragment |
+| `.not(obj)` | AND NOT conditions (`null` becomes `IS NOT NULL`) |
+| `.not(sql, params)` | AND NOT with raw SQL fragment |
+| `.select(cols)` | Columns to select (string or array) |
+| `.order(expr)` | ORDER BY expression |
+| `.group(expr)` | GROUP BY expression |
+| `.having(sql, params)` | HAVING clause with params |
+| `.limit(n)` | LIMIT |
+| `.offset(n)` | OFFSET |
+| `.all!` | Execute, return array of objects |
+| `.first!` | Execute with LIMIT 1, return object or null |
+| `.count!` | Execute COUNT(*), return number |
+| `.update!(data)` | Bulk UPDATE matching rows, return array |
+| `.destroy!` | Bulk DELETE matching rows, return array |
+
+### Model Reference
+
+| Method | Description |
+|--------|-------------|
+| `Model.find!(id)` | Find by primary key |
+| `Model.all!(limit?)` | All rows, optional limit |
+| `Model.count!` | Count all rows |
+| `Model.where(...)` | Start a query chain |
+| `Model.or(...)` | Start a chain with OR |
+| `Model.not(...)` | Start a chain with NOT |
+| `Model.select(...)` | Start a chain with SELECT |
+| `Model.order(...)` | Start a chain with ORDER BY |
+| `Model.group(...)` | Start a chain with GROUP BY |
+| `Model.limit(n)` | Start a chain with LIMIT |
+| `Model.insert!(data)` | Insert and return new row |
+| `Model.update!(id, data)` | Update by id and return row |
+| `Model.upsert!(data, on:)` | Insert or update on conflict |
+| `Model.destroy!(id)` | Delete by id and return row |
+| `Model.query!(sql, params)` | Raw parameterized query |
+
 ## DuckDB UI
 
 The official DuckDB UI is available at the root URL. It provides:

package/client.rip

@@ -0,0 +1,289 @@
+# @rip-lang/db/client — Database client with chainable Model factory
+#
+# Connects to a rip-db server over HTTP. Provides parameterized queries
+# and an ActiveRecord-style Model for common CRUD operations.
+#
+# Usage:
+#   import { query, findOne, findAll, Model } from '@rip-lang/db/client'
+#
+#   # Low-level
+#   result = query! "SELECT * FROM users WHERE id = $1", [42]
+#   user   = findOne! "SELECT * FROM users WHERE id = $1", [42]
+#   users  = findAll! "SELECT * FROM users WHERE active = $1", [true]
+#
+#   # Model
+#   User = Model 'users'
+#   user  = User.find! 42
+#   users = User.where(active: true).order('name').limit(10).all!
+#   user  = User.insert! { name: 'Alice', email: 'alice@example.com' }
+#   user  = User.upsert! { email: 'alice@example.com', name: 'Alice' }, on: 'email'
+#   user  = User.update! 42, { name: 'Bob' }
+#   User.destroy! 42
+#   users = User.where(active: true).or('role = $1', ['admin']).all!
+#   users = User.where(active: true).not(role: 'banned').all!
+#   stats = User.group('role').select('role, count(*) as n').all!
+
+# ==============================================================================
+# Connection
+# ==============================================================================
+
+_dbUrl = null
+
+export connect = (url) -> _dbUrl = url
+
+dbUrl = -> _dbUrl or process.env.DB_URL or 'http://localhost:4213'
+
+# ==============================================================================
+# Low-Level Helpers
+# ==============================================================================
+
+export esc = (v) ->
+  return 'NULL' unless v?
+  return String(v) if typeof v is 'number'
+  "'" + String(v).replace(/'/g, "''") + "'"
+
+export query = (sql, params = []) ->
+  body = if params.length > 0 then { sql, params } else { sql }
+  res = fetch! "#{dbUrl()}/sql",
+    method: 'POST'
+    headers: { 'Content-Type': 'application/json' }
+    body: JSON.stringify body
+  data = res.json!
+  throw new Error data.error if data.error
+  data
+
+materialize = (meta, row) ->
+  obj = {}
+  for col, i in meta
+    obj[col.name] = row[i]
+  obj
+
+export materializeAll = (result) ->
+  return [] if result.rows is 0
+  result.data.map (row) -> materialize result.meta, row
+
+export findOne = (sql, params = []) ->
+  result = query! sql, params
+  return null if result.rows is 0
+  materialize result.meta, result.data[0]
+
+export findAll = (sql, params = []) ->
+  result = query! sql, params
+  materializeAll result
+
+# ==============================================================================
+# Query Builder
+# ==============================================================================
+
+class QueryBuilder
+  constructor: (@table, @database = null) ->
+    @_tableName = if @database then "\"#{@database}\".\"#{@table}\"" else "\"#{@table}\""
+    @_wheres  = []
+    @_params  = []
+    @_order   = null
+    @_group   = null
+    @_having  = null
+    @_limit   = null
+    @_offset  = null
+    @_select  = '*'
+
+  select: (cols) ->
+    b = @_clone()
+    b._select = if Array.isArray(cols) then cols.join(', ') else cols
+    b
+
+  where: (conditions, params = []) ->
+    b = @_clone()
+    if typeof conditions is 'string'
+      b._wheres.push { clause: conditions, join: 'AND' }
+      b._params = b._params.concat params
+    else if typeof conditions is 'object'
+      for own key, val of conditions
+        if val is null
+          b._wheres.push { clause: "\"#{key}\" IS NULL", join: 'AND' }
+        else
+          b._wheres.push { clause: "\"#{key}\" = $#{b._params.length + 1}", join: 'AND' }
+          b._params.push val
+    b
+
+  or: (conditions, params = []) ->
+    b = @_clone()
+    if typeof conditions is 'string'
+      b._wheres.push { clause: conditions, join: 'OR' }
+      b._params = b._params.concat params
+    else if typeof conditions is 'object'
+      parts = []
+      for own key, val of conditions
+        if val is null
+          parts.push "\"#{key}\" IS NULL"
+        else
+          parts.push "\"#{key}\" = $#{b._params.length + 1}"
+          b._params.push val
+      b._wheres.push { clause: "(#{parts.join(' AND ')})", join: 'OR' }
+    b
+
+  not: (conditions, params = []) ->
+    b = @_clone()
+    if typeof conditions is 'string'
+      b._wheres.push { clause: "NOT (#{conditions})", join: 'AND' }
+      b._params = b._params.concat params
+    else if typeof conditions is 'object'
+      for own key, val of conditions
+        if val is null
+          b._wheres.push { clause: "\"#{key}\" IS NOT NULL", join: 'AND' }
+        else
+          b._wheres.push { clause: "\"#{key}\" != $#{b._params.length + 1}", join: 'AND' }
+          b._params.push val
+    b
+
+  order: (expr) ->
+    b = @_clone()
+    b._order = expr
+    b
+
+  group: (expr) ->
+    b = @_clone()
+    b._group = expr
+    b
+
+  having: (clause, params = []) ->
+    b = @_clone()
+    b._having = clause
+    b._params = b._params.concat params
+    b
+
+  limit: (n) ->
+    b = @_clone()
+    b._limit = n
+    b
+
+  offset: (n) ->
+    b = @_clone()
+    b._offset = n
+    b
+
+  _buildWhere: ->
+    return '' if @_wheres.length is 0
+    parts = []
+    for w, i in @_wheres
+      if i is 0
+        parts.push w.clause
+      else
+        parts.push "#{w.join} #{w.clause}"
+    " WHERE #{parts.join(' ')}"
+
+  _toSQL: ->
+    sql = "SELECT #{@_select} FROM #{@_tableName}"
+    sql += @_buildWhere()
+    sql += " GROUP BY #{@_group}" if @_group
+    sql += " HAVING #{@_having}" if @_having
+    sql += " ORDER BY #{@_order}" if @_order
+    sql += " LIMIT #{@_limit}" if @_limit?
+    sql += " OFFSET #{@_offset}" if @_offset?
+    sql
+
+  all: ->
+    findAll! @_toSQL(), @_params
+
+  first: ->
+    b = @_clone()
+    b._limit = 1
+    findOne! b._toSQL(), b._params
+
+  count: ->
+    sql = "SELECT COUNT(*) as count FROM #{@_tableName}"
+    sql += @_buildWhere()
+    sql += " GROUP BY #{@_group}" if @_group
+    sql += " HAVING #{@_having}" if @_having
+    result = query! sql, @_params
+    result.data[0][0]
+
+  update: (data) ->
+    keys = Object.keys(data).filter (k) -> data[k] isnt undefined
+    sets = keys.map((k, i) -> "\"#{k}\" = $#{@_params.length + i + 1}").join(', ')
+    vals = keys.map (k) -> data[k]
+    allParams = [...@_params, ...vals]
+    sql = "UPDATE #{@_tableName} SET #{sets}"
+    sql += @_buildWhere()
+    sql += " RETURNING *"
+    findAll! sql, allParams
+
+  destroy: ->
+    sql = "DELETE FROM #{@_tableName}"
+    sql += @_buildWhere()
+    sql += " RETURNING *"
+    findAll! sql, @_params
+
+  _clone: ->
+    b = new QueryBuilder(@table, @database)
+    b._wheres = [...@_wheres]
+    b._params = [...@_params]
+    b._order  = @_order
+    b._group  = @_group
+    b._having = @_having
+    b._limit  = @_limit
+    b._offset = @_offset
+    b._select = @_select
+    b
+
+# ==============================================================================
+# Model Factory
+# ==============================================================================
+
+export Model = (table, database = null) ->
+  tableName = if database then "\"#{database}\".\"#{table}\"" else "\"#{table}\""
+  _qb = -> new QueryBuilder(table, database)
+
+  find: (id) ->
+    findOne! "SELECT * FROM #{tableName} WHERE id = $1", [id]
+
+  all: (limit = null) ->
+    sql = "SELECT * FROM #{tableName}"
+    sql += " LIMIT #{limit}" if limit?
+    findAll! sql
+
+  where: (conditions, params = []) -> _qb().where(conditions, params)
+  or:    (conditions, params = []) -> _qb().or(conditions, params)
+  not:   (conditions, params = []) -> _qb().not(conditions, params)
+  select: (cols) -> _qb().select(cols)
+  order:  (expr) -> _qb().order(expr)
+  group:  (expr) -> _qb().group(expr)
+  limit:  (n)    -> _qb().limit(n)
+
+  count: ->
+    result = query! "SELECT COUNT(*) as count FROM #{tableName}"
+    result.data[0][0]
+
+  query: (sql, params = []) ->
+    findAll! sql, params
+
+  insert: (data) ->
+    keys = Object.keys(data).filter (k) -> data[k] isnt undefined
+    cols = keys.map((k) -> "\"#{k}\"").join(', ')
+    refs = keys.map((_, i) -> "$#{i + 1}").join(', ')
+    vals = keys.map (k) -> data[k]
+    findOne! "INSERT INTO #{tableName} (#{cols}) VALUES (#{refs}) RETURNING *", vals
+
+  update: (id, data) ->
+    keys = Object.keys(data).filter (k) -> data[k] isnt undefined
+    sets = keys.map((k, i) -> "\"#{k}\" = $#{i + 2}").join(', ')
+    vals = keys.map (k) -> data[k]
+    findOne! "UPDATE #{tableName} SET #{sets} WHERE id = $1 RETURNING *", [id, ...vals]
+
+  upsert: (data, opts = {}) ->
+    keys = Object.keys(data).filter (k) -> data[k] isnt undefined
+    cols = keys.map((k) -> "\"#{k}\"").join(', ')
+    refs = keys.map((_, i) -> "$#{i + 1}").join(', ')
+    vals = keys.map (k) -> data[k]
+
+    conflict = opts.on or opts.conflict
+    sql = "INSERT INTO #{tableName} (#{cols}) VALUES (#{refs})"
+    if conflict
+      updateCols = keys.filter((k) -> k isnt conflict)
+      sets = updateCols.map((k) -> "\"#{k}\" = EXCLUDED.\"#{k}\"").join(', ')
+      sql += " ON CONFLICT (\"#{conflict}\") DO UPDATE SET #{sets}"
+    sql += " RETURNING *"
+    findOne! sql, vals
+
+  destroy: (id) ->
+    findOne! "DELETE FROM #{tableName} WHERE id = $1 RETURNING *", [id]

package/db.rip

@@ -125,8 +125,8 @@ isSelectQuery = (sql) ->
 
 # Log SQL query (truncated if long)
 logSQL = (sql) ->
-  query = sql.replace(/\s+/g, ' ').trim()
-  console.log "SQL: #{query}"
+  # sql = sql.replace(/\s+/g, ' ').trim()
+  console.log sql
 
 # Execute SQL and return result (uses persistent connection)
 executeSQL = (sql, params = []) ->
@@ -224,7 +224,7 @@ getUIParams = (req) ->
 # POST /ddb/run — Execute SQL and return binary result (DuckDB UI protocol)
 post '/ddb/run' ->
   try
-    sql = read 'body', 'string'
+    sql = read 'body', 'raw'
     return binaryResponse serializeErrorResult 'Empty query' unless sql
 
     logSQL sql

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@rip-lang/db",
-  "version": "1.1.8",
+  "version": "1.2.0",
   "description": "DuckDB server with official DuckDB UI — pure Bun FFI",
   "type": "module",
   "main": "db.rip",
+  "exports": {
+    ".": "./db.rip",
+    "./client": "./client.rip"
+  },
   "bin": {
     "rip-db": "./bin/rip-db"
   },
@@ -39,6 +43,7 @@
   },
   "files": [
     "db.rip",
+    "client.rip",
     "lib/",
     "bin/",
     "README.md"