arn-db 0.1.0 → 0.2.1

package/dist/index.d.mts

@@ -52,6 +52,47 @@ export declare class Now {
 type Column = string | Col;
 export declare const col: (name: string) => Col;
 export declare const now: () => Now;
+/**
+ * A raw SQL fragment: one expression inside the query the builder makes, with
+ * `?` for each binding (`\\?` is a literal `?`, e.g. the jsonb `?` operator).
+ * Bindings are sent as query parameters, never pasted into the SQL. Use it in
+ * `where()`, `order()`, `having()`, as a `select()` column with `.as()`, and as
+ * an insert/update/upsert value or upsert `merge` value. The API key must be
+ * allowed to use raw fragments.
+ *
+ *   .where(db.raw('lower(email) = any(?)', [emails]))
+ *   .update({ sent_total: db.raw('sent_total + ?', [1]) })
+ */
+export declare class Raw {
+  #private;
+  readonly sql: string;
+  readonly bindings: unknown[];
+  constructor(sql: string, bindings?: unknown[], as?: string);
+  /** Name of this fragment as a `select()` column: `raw('char_length(title)').as('title_len')`. */
+  as(name: string): Raw;
+  /** @internal The `.as()` name, if any. */
+  alias(): string | undefined;
+  /** @internal The fragment without its name, for filters, order and having. */
+  fragment(): {
+    $raw: string;
+    bindings: unknown[];
+  };
+  /** @internal Wire format. */
+  toJSON(): {
+    $raw: string;
+    bindings: unknown[];
+    as?: string;
+  };
+}
+/**
+ * A raw SQL fragment with `?` bindings: knex's `whereRaw` / `orderByRaw` /
+ * `havingRaw` / `knex.raw` value. Throws if `sql` is not a non-empty string
+ * or `bindings` not an array; the server checks the rest.
+ *
+ * @example
+ * db.from('users').select().where(raw('lower(trim(email)) = any(?)', [emails]))
+ */
+export declare const raw: (sql: string, bindings?: unknown[]) => Raw;
 /**
  * Atomic update operator, applied by Postgres to the current column value.
  *
@@ -150,9 +191,21 @@ interface GroupFilter {
   group: 'and' | 'or' | 'not';
   filters: Filter[];
 }
-type Filter = ConditionFilter | GroupFilter;
+/** A raw SQL fragment on the wire: `?` placeholders and their values. */
+interface RawFragment {
+  $raw: string;
+  bindings: unknown[];
+}
+/** A `where(raw(...))` condition: `AND (<fragment>)`, or one member of an OR group. */
+interface RawFilter {
+  op: 'raw';
+  value: RawFragment;
+}
+type Filter = ConditionFilter | GroupFilter | RawFilter;
 interface Order {
   column?: string;
+  /** `order(raw(...))`: sort by the fragment instead of a column. */
+  raw?: RawFragment;
   ascending?: boolean;
   nullsFirst?: boolean;
   random?: boolean;
@@ -180,8 +233,14 @@ interface QueryRequest {
   upsert?: boolean;
   onConflict?: string[];
   ignoreDuplicates?: boolean;
-  merge?: Record<string, MergeMode | Op>;
+  merge?: Record<string, MergeMode | Op | Raw>;
   groupBy?: string[];
+  /** `having(raw(...))` fragments, joined with AND. Only with `groupBy`. */
+  having?: RawFragment[];
+  /** `select(..., raw(...).as(name))` columns of the main table. */
+  rawColumns?: (RawFragment & {
+    as: string;
+  })[];
   distinct?: boolean;
   aggregate?: {
     fn: AggregateFn;
@@ -210,14 +269,21 @@ interface UpsertOptions {
   /**
    * Change only these columns of an existing row; the rest keep their stored
    * value. Each is a {@link MergeMode} or a `db.ops` value applied to the stored
-   * value. A list of names means `'set'` for each. Without `merge`, every column
-   * you send (except the conflict key) is replaced.
+   * value, or a `db.raw` fragment (`excluded.col` is the incoming value). A
+   * list of names means `'set'` for each. Without `merge`, every column you
+   * send (except the conflict key) is replaced.
    *
    * @example
    * merge: { total: 'add', email: 'set', hits: db.ops.increment(1) }
+   * merge: { total: db.raw('greatest(accounts.total, excluded.total)') }
    * merge: ['email', 'name']
    */
-  merge?: Record<string, MergeMode | Op> | string[];
+  merge?: Record<string, MergeMode | Op | Raw> | string[];
+}
+/** `select()` options: `count: 'exact'` also fills `count`; `head: true` skips the rows. */
+interface SelectOptions {
+  count?: 'exact';
+  head?: boolean;
 }
 /** Options for `order()`, `random()` and `limit()` that target an embedded table. */
 interface ReferencedTableOption {
@@ -235,6 +301,8 @@ interface TxStepRequest extends QueryRequest {
 /** Filter methods, shared by builders and groups. */
 declare abstract class Filters {
   #private;
+  /** @internal A problem found while building, reported instead of sending. */
+  protected problem: string | undefined;
   /** @internal Adds one filter or group. */
   protected abstract push(filter: Filter): void;
   /**
@@ -317,6 +385,17 @@ declare abstract class Filters {
    * .match({ active: true, age: 30 })
    */
   match(values: Row): this;
+  /**
+   * A raw SQL condition, knex's `whereRaw`: `AND (<fragment>)`, or one member
+   * of an `or()` group. Only takes `raw()`; for a column use `eq()` and friends.
+   * The fragment sees the main table's columns, not related tables.
+   *
+   * @example
+   * .where(db.raw('lower(trim(email)) = any(?)', [emails]))
+   * .where(db.raw('sent_per_hour < limit_per_hour'))
+   * .or((q) => q.where(db.raw('meta \\? ?', ['vip'])).eq('age', 30))   // jsonb ? operator
+   */
+  where(fragment: Raw): this;
   /**
    * Any of the conditions.
    *
@@ -364,8 +443,6 @@ declare abstract class Builder<T extends Row, R> extends Filters implements Prom
   #private;
   /** @internal */ protected readonly transport: Transport | null;
   /** @internal */ protected readonly req: QueryRequest;
-  /** @internal A problem found while building, reported instead of sending. */
-  protected problem: string | undefined;
   /** @internal */
   constructor(transport: Transport | null, req: QueryRequest, name?: string, problem?: string);
   /** @internal */
@@ -416,11 +493,14 @@ export declare class QueryBuilder<T extends Row = Row, R = T[]> extends Builder<
    * db.from('users').select('name, posts!user_id!inner(title)')  // only users that have posts
    * db.from('users').select('name, posts!user_id(count)')         // posts: [{ count: 2 }]
    * db.from('posts').select('*', { count: 'exact' }).range(0, 9)  // rows + total
+   *
+   * Extra `raw(...).as(name)` arguments add SQL expressions of the main table
+   * as columns (options, if any, go last).
+   *
+   * @example
+   * db.from('posts').select('id, title', db.raw('char_length(title)').as('title_len'))
    */
-  select(columns?: string, options?: {
-    count?: 'exact';
-    head?: boolean;
-  }): QueryBuilder<T, T[]>;
+  select(columns?: string, ...extra: (Raw | SelectOptions)[]): QueryBuilder<T, T[]>;
   /**
    * Number of matching rows: `data` is the number. All filters apply, including
    * jsonb paths and `relation.column` filters on `!inner` relations.
@@ -455,6 +535,14 @@ export declare class QueryBuilder<T extends Row = Row, R = T[]> extends Builder<
    * db.from('posts').select('user_id, n:count(), last:max(created_at)').groupBy('user_id').order('n', { ascending: false })
    */
   groupBy(columns: string): this;
+  /**
+   * Keep only the groups where the raw condition holds, knex's `havingRaw`.
+   * Use with `groupBy()`; several calls are joined with AND.
+   *
+   * @example
+   * db.from('posts').select('user_id, n:count()').groupBy('user_id').having(db.raw('count(*) >= ?', [2]))
+   */
+  having(fragment: Raw): this;
   /**
    * Leave out repeated rows: `SELECT DISTINCT`.
    *
@@ -540,8 +628,9 @@ export declare class QueryBuilder<T extends Row = Row, R = T[]> extends Builder<
    * .order('active', { ascending: false }).order('age', { ascending: false }).order('name')
    * .order('meta->>score::int', { ascending: false, nullsFirst: false })
    * .order('title', { referencedTable: 'posts' })   // posts inside each user
+   * .order(db.raw("coalesce(last_read_time, '1970-01-01')"))   // raw, main table only
    */
-  order(column: string, options?: {
+  order(column: string | Raw, options?: {
     ascending?: boolean;
     nullsFirst?: boolean;
   } & ReferencedTableOption): this;
@@ -722,6 +811,8 @@ interface Tx {
   readonly col: typeof col;
   /** The database server's time, same as `db.now`. */
   readonly now: typeof now;
+  /** A raw SQL fragment, same as `db.raw`. */
+  readonly raw: typeof raw;
 }
 interface Client {
   from<T extends Row = Row>(table: string): QueryBuilder<T>;
@@ -756,6 +847,16 @@ interface Client {
    * await db.from('accounts').update({ last_read_time: db.now() }).eq('id', id)
    */
   readonly now: typeof now;
+  /**
+   * A raw SQL fragment with `?` bindings (same as `import { raw }`), for
+   * `where()`, `order()`, `having()`, `select()` columns and write values.
+   * The API key must be allowed to use raw fragments.
+   *
+   * @example
+   * await db.from('accounts').select().where(db.raw('sent_per_hour < limit_per_hour'))
+   * await db.from('accounts').update({ sent_total: db.raw('sent_total + ?', [1]) }).eq('id', id)
+   */
+  readonly raw: typeof raw;
   /**
    * Run several steps in one database transaction: all succeed or nothing is saved.
    * On failure `error.step` / `error.stepName` say which step failed.
@@ -794,5 +895,5 @@ export declare function createClient(url: string, apiKey: string, options?: Clie
  * const { data, error } = await db.from('users').select().eq('id', id).single()
  */
 export declare const db: Client;
-export type { AggregateFn, Client, ClientOptions, Column, ConditionFilter, Filter, FilterOp, GroupFilter, Key, MergeMode, Order, PgError, QueryRequest, QueryResult, ReadFrom, Ref, ReferencedTableOption, RelOp, RelOpName, Row, Step, StepData, Tx, TxStepRequest, UpsertOptions };
+export type { AggregateFn, Client, ClientOptions, Column, ConditionFilter, Filter, FilterOp, GroupFilter, Key, MergeMode, Order, PgError, QueryRequest, QueryResult, RawFilter, RawFragment, ReadFrom, Ref, ReferencedTableOption, RelOp, RelOpName, Row, SelectOptions, Step, StepData, Tx, TxStepRequest, UpsertOptions };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -151,10 +151,66 @@ var Now = class Now {
 };
 const col = (name) => new Col(name);
 const now = () => new Now();
+/**
+* A raw SQL fragment: one expression inside the query the builder makes, with
+* `?` for each binding (`\\?` is a literal `?`, e.g. the jsonb `?` operator).
+* Bindings are sent as query parameters, never pasted into the SQL. Use it in
+* `where()`, `order()`, `having()`, as a `select()` column with `.as()`, and as
+* an insert/update/upsert value or upsert `merge` value. The API key must be
+* allowed to use raw fragments.
+*
+*   .where(db.raw('lower(email) = any(?)', [emails]))
+*   .update({ sent_total: db.raw('sent_total + ?', [1]) })
+*/
+var Raw = class Raw {
+	sql;
+	bindings;
+	#as;
+	constructor(sql, bindings = [], as) {
+		if (typeof sql !== "string" || sql.trim() === "") throw new Error("arn-db: raw(sql) needs a non-empty SQL string");
+		if (!Array.isArray(bindings)) throw new Error("arn-db: raw(sql, bindings) takes the bindings as an array");
+		this.sql = sql;
+		this.bindings = bindings;
+		this.#as = as;
+	}
+	/** Name of this fragment as a `select()` column: `raw('char_length(title)').as('title_len')`. */
+	as(name) {
+		return new Raw(this.sql, this.bindings, name);
+	}
+	/** @internal The `.as()` name, if any. */
+	alias() {
+		return this.#as;
+	}
+	/** @internal The fragment without its name, for filters, order and having. */
+	fragment() {
+		return {
+			$raw: this.sql,
+			bindings: this.bindings
+		};
+	}
+	/** @internal Wire format. */
+	toJSON() {
+		return this.#as === void 0 ? this.fragment() : {
+			...this.fragment(),
+			as: this.#as
+		};
+	}
+};
+/**
+* A raw SQL fragment with `?` bindings: knex's `whereRaw` / `orderByRaw` /
+* `havingRaw` / `knex.raw` value. Throws if `sql` is not a non-empty string
+* or `bindings` not an array; the server checks the rest.
+*
+* @example
+* db.from('users').select().where(raw('lower(trim(email)) = any(?)', [emails]))
+*/
+const raw = (sql, bindings) => new Raw(sql, bindings);
 // src/builder.ts
 const embedOf = (o) => o.referencedTable ?? o.foreignTable;
 /** Filter methods, shared by builders and groups. */
 var Filters = class {
+	/** @internal A problem found while building, reported instead of sending. */
+	problem;
 	#filter(column, op, value) {
 		if (column instanceof Col) {
 			const ifNull = column.nullValue();
@@ -287,6 +343,24 @@ var Filters = class {
 		return this;
 	}
 	/**
+	* A raw SQL condition, knex's `whereRaw`: `AND (<fragment>)`, or one member
+	* of an `or()` group. Only takes `raw()`; for a column use `eq()` and friends.
+	* The fragment sees the main table's columns, not related tables.
+	*
+	* @example
+	* .where(db.raw('lower(trim(email)) = any(?)', [emails]))
+	* .where(db.raw('sent_per_hour < limit_per_hour'))
+	* .or((q) => q.where(db.raw('meta \\? ?', ['vip'])).eq('age', 30))   // jsonb ? operator
+	*/
+	where(fragment) {
+		if (fragment instanceof Raw) this.push({
+			op: "raw",
+			value: fragment.fragment()
+		});
+		else this.problem ??= "where() takes a raw() fragment; for a column use eq(), gt(), in() and friends";
+		return this;
+	}
+	/**
 	* Any of the conditions.
 	*
 	* @example
@@ -313,6 +387,7 @@ var Filters = class {
 	#group(group, conditions) {
 		const q = new FilterGroup();
 		conditions(q);
+		if (q.problem) this.problem ??= q.problem;
 		this.push({
 			group,
 			filters: q.filters
@@ -339,8 +414,6 @@ var FilterGroup = class extends Filters {
 var Builder = class extends Filters {
 	/** @internal */ transport;
 	/** @internal */ req;
-	/** @internal A problem found while building, reported instead of sending. */
-	problem;
 	#name;
 	/** @internal */
 	constructor(transport, req, name, problem) {
@@ -444,11 +517,30 @@ var QueryBuilder = class extends Builder {
 	* db.from('users').select('name, posts!user_id!inner(title)')  // only users that have posts
 	* db.from('users').select('name, posts!user_id(count)')         // posts: [{ count: 2 }]
 	* db.from('posts').select('*', { count: 'exact' }).range(0, 9)  // rows + total
+	*
+	* Extra `raw(...).as(name)` arguments add SQL expressions of the main table
+	* as columns (options, if any, go last).
+	*
+	* @example
+	* db.from('posts').select('id, title', db.raw('char_length(title)').as('title_len'))
 	*/
-	select(columns = "*", options = {}) {
+	select(columns = "*", ...extra) {
 		this.req.columns = columns;
-		if (options.count) this.req.count = true;
-		if (options.head) this.req.head = true;
+		const rawColumns = [];
+		for (const e of extra) if (e instanceof Raw) {
+			const as = e.alias();
+			if (as === void 0) this.problem ??= `raw("${e.sql}") in select() needs a column name: add .as('name')`;
+			else if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(as)) this.problem ??= `raw(...).as("${as}"): the name must be letters, digits and _`;
+			else rawColumns.push({
+				...e.fragment(),
+				as
+			});
+		} else if (e) {
+			if (e.count) this.req.count = true;
+			if (e.head) this.req.head = true;
+		}
+		if (rawColumns.length) this.req.rawColumns = rawColumns;
+		else delete this.req.rawColumns;
 		return this;
 	}
 	/**
@@ -510,6 +602,18 @@ var QueryBuilder = class extends Builder {
 		return this;
 	}
 	/**
+	* Keep only the groups where the raw condition holds, knex's `havingRaw`.
+	* Use with `groupBy()`; several calls are joined with AND.
+	*
+	* @example
+	* db.from('posts').select('user_id, n:count()').groupBy('user_id').having(db.raw('count(*) >= ?', [2]))
+	*/
+	having(fragment) {
+		if (fragment instanceof Raw) (this.req.having ??= []).push(fragment.fragment());
+		else this.problem ??= "having() takes a raw() fragment: having(db.raw(\"count(*) >= ?\", [2]))";
+		return this;
+	}
+	/**
 	* Leave out repeated rows: `SELECT DISTINCT`.
 	*
 	* @example
@@ -636,9 +740,19 @@ var QueryBuilder = class extends Builder {
 	* .order('active', { ascending: false }).order('age', { ascending: false }).order('name')
 	* .order('meta->>score::int', { ascending: false, nullsFirst: false })
 	* .order('title', { referencedTable: 'posts' })   // posts inside each user
+	* .order(db.raw("coalesce(last_read_time, '1970-01-01')"))   // raw, main table only
 	*/
 	order(column, options = {}) {
 		const { ascending = true, nullsFirst } = options;
+		if (column instanceof Raw) {
+			if (embedOf(options)) this.problem ??= "order(raw(...)) sorts the main table only: drop referencedTable";
+			else this.req.order.push({
+				raw: column.fragment(),
+				ascending,
+				nullsFirst
+			});
+			return this;
+		}
 		this.req.order.push({
 			column,
 			ascending,
@@ -920,6 +1034,7 @@ function createClient(url, apiKey, options = {}) {
 		rel,
 		col,
 		now,
+		raw,
 		async transaction(build) {
 			const steps = toSteps(build({
 				from: (table) => new QueryBuilder(null, table),
@@ -927,7 +1042,8 @@ function createClient(url, apiKey, options = {}) {
 				ops,
 				rel,
 				col,
-				now
+				now,
+				raw
 			}));
 			if (typeof steps === "string") return fail(steps);
 			const res = await transport.post("/transaction", { steps: steps.wire });
@@ -943,14 +1059,20 @@ function createClient(url, apiKey, options = {}) {
 }
 // src/env.ts
 let client;
+const proc = globalThis.process;
+/** Reads ./.env into process.env (Node 20.12+; never overrides set vars). */
+function loadDotEnv() {
+	if (!proc?.loadEnvFile) return;
+	try {
+		proc.loadEnvFile();
+	} catch {}
+}
+loadDotEnv();
 /** The ARN_DB_URL / ARN_DB_KEY client, made on the first query (so a later dotenv still counts). */
 function envClient() {
 	if (client) return client;
-	const proc = globalThis.process;
 	if (!proc) throw new Error("arn-db: `db` reads ARN_DB_URL / ARN_DB_KEY from process.env; use createClient(url, key) here");
-	if ((!proc.env.ARN_DB_URL || !proc.env.ARN_DB_KEY) && proc.loadEnvFile) try {
-		proc.loadEnvFile();
-	} catch {}
+	if (!proc.env.ARN_DB_URL || !proc.env.ARN_DB_KEY) loadDotEnv();
 	const url = proc.env.ARN_DB_URL;
 	const key = proc.env.ARN_DB_KEY;
 	if (!url) throw new Error("arn-db: set ARN_DB_URL (e.g. https://your-api.example.com/v2/raw) or use createClient(url, key)");
@@ -974,8 +1096,9 @@ const db = {
 	ops,
 	rel,
 	col,
-	now
+	now,
+	raw
 };
-export { Col, FilterGroup, Now, Op, QueryBuilder, WriteBuilder, col, createClient, db, now, ops, rel };
+export { Col, FilterGroup, Now, Op, QueryBuilder, Raw, WriteBuilder, col, createClient, db, now, ops, raw, rel };
 
 //# sourceMappingURL=index.mjs.map