arn-db 0.0.0-stage → 0.2.0

package/dist/index.cjs

@@ -0,0 +1,1112 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+// src/rel.ts
+const list = (v) => Array.isArray(v) ? v : [v];
+/** "user_id, title" -> { onConflict: ['user_id', 'title'] } */
+const conflict = (columns) => columns ? { onConflict: columns.split(",").map((c) => c.trim()).filter(Boolean) } : {};
+const rel = {
+	/**
+	* Insert related rows (they may contain `rel.*` themselves).
+	* @example
+	* db.from('posts').insert({ title, user_id, comments: rel.create([{ body, author_id }]) })
+	*/
+	create: (rows) => ({
+		$rel: "create",
+		rows: list(rows)
+	}),
+	/**
+	* Insert one related row, or update it if its `onConflict` key (default: primary key) exists.
+	* @example
+	* db.from('posts').update({ comments: rel.upsert({ id: commentId, body: 'v2', author_id }) }).eq('id', postId)
+	*/
+	upsert: (row, options = {}) => ({
+		$rel: "upsert",
+		rows: [row],
+		...conflict(options.onConflict)
+	}),
+	/**
+	* Find one related row by its `onConflict` key (default: primary key), or create it,
+	* then link it. An existing row is not changed.
+	* @example
+	* db.from('posts').insert({ title, user_id, labels: rel.connectOrCreate({ name: 'go' }, { onConflict: 'name' }) })
+	*/
+	connectOrCreate: (row, options = {}) => ({
+		$rel: "connectOrCreate",
+		rows: [row],
+		...conflict(options.onConflict)
+	}),
+	/**
+	* Link existing rows by key. Fails (and rolls back) if a key does not exist.
+	* @example
+	* db.from('posts').update({ labels: rel.connect([labelA, labelB]) }).eq('id', postId)
+	*/
+	connect: (keys) => ({
+		$rel: "connect",
+		keys: list(keys)
+	}),
+	/**
+	* Unlink rows by key (many-to-one: clears the FK; one-to-many: sets the child FK to null).
+	* @example
+	* db.from('posts').update({ labels: rel.disconnect(labelId) }).eq('id', postId)
+	*/
+	disconnect: (keys = []) => ({
+		$rel: "disconnect",
+		keys: list(keys)
+	}),
+	/**
+	* Make exactly these rows linked: unlinks the others, links the missing ones.
+	* @example
+	* db.from('posts').update({ labels: rel.set([labelA]) }).eq('id', postId)   // rel.set([]) unlinks all
+	*/
+	set: (keys) => ({
+		$rel: "set",
+		keys
+	}),
+	/**
+	* Update linked rows that match (equality on every key of `match`).
+	* @example
+	* db.from('posts').update({ comments: rel.update({ id: commentId }, { body: 'edited' }) }).eq('id', postId)
+	*/
+	update: (match, values) => ({
+		$rel: "update",
+		match,
+		values
+	}),
+	/**
+	* Delete linked rows that match; `rel.delete()` deletes all linked rows.
+	* @example
+	* db.from('posts').update({ comments: rel.delete({ body: 'spam' }) }).eq('id', postId)
+	*/
+	delete: (match = {}) => ({
+		$rel: "delete",
+		match
+	})
+};
+// src/values.ts
+/**
+* Values the database fills in: another column of the same row (`db.col`)
+* and the database's current time (`db.now`).
+*/
+/**
+* Another column of the same row. As a filter value it compares two columns;
+* as the column of a filter it lets `ifNull()` replace NULL first.
+*
+*   .lt('sent_per_hour', db.col('limit_per_hour'))
+*   .lt(db.col('sent_per_hour').ifNull(0), db.col('limit_per_hour'))
+*/
+var Col = class Col {
+	name;
+	#ifNull;
+	constructor(name, ifNull) {
+		this.name = name;
+		this.#ifNull = ifNull;
+	}
+	/** Use `value` where the column is NULL: `COALESCE(column, value)`. */
+	ifNull(value) {
+		return new Col(this.name, { value });
+	}
+	/** @internal The NULL replacement, if any. */
+	nullValue() {
+		return this.#ifNull;
+	}
+	/** @internal Wire format. */
+	toJSON() {
+		return this.#ifNull ? {
+			$col: this.name,
+			ifNull: this.#ifNull.value
+		} : { $col: this.name };
+	}
+};
+/**
+* The database server's `now()`, optionally shifted by one interval like
+* `'1 hour'` or `'30 minutes'` (units: second, minute, hour, day, week,
+* month, year). Works in filters and in insert/update values.
+*
+*   .lte('client_sent_time', db.now().minus('1 hour'))
+*   .update({ last_read_time: db.now() })
+*/
+var Now = class Now {
+	#interval;
+	constructor(interval) {
+		this.#interval = interval;
+	}
+	/** Later by `interval`: `db.now().plus('1 day')`. */
+	plus(interval) {
+		return this.#shift(interval.trim());
+	}
+	/** Earlier by `interval`: `db.now().minus('1 hour')`. */
+	minus(interval) {
+		const i = interval.trim();
+		return this.#shift(i.startsWith("-") ? i.slice(1) : `-${i}`);
+	}
+	#shift(interval) {
+		if (this.#interval !== void 0) throw new Error("arn-db: db.now() takes one plus() or minus(); use a single interval");
+		return new Now(interval);
+	}
+	/** @internal Wire format. */
+	toJSON() {
+		return this.#interval === void 0 ? { $now: true } : {
+			$now: true,
+			interval: this.#interval
+		};
+	}
+};
+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();
+			this.push(ifNull ? {
+				column: column.name,
+				op,
+				value,
+				ifNull: ifNull.value
+			} : {
+				column: column.name,
+				op,
+				value
+			});
+		} else this.push({
+			column,
+			op,
+			value
+		});
+		return this;
+	}
+	/**
+	* Equal. Works on columns, jsonb paths and related tables.
+	*
+	* @example
+	* .eq('active', true)
+	* .eq('meta->>city', 'Tokyo')
+	* .eq('posts.published', true)       // filters the related posts
+	*/
+	eq(column, value) {
+		return this.#filter(column, "eq", value);
+	}
+	/** Not equal. */
+	neq(column, value) {
+		return this.#filter(column, "neq", value);
+	}
+	/**
+	* Greater than. For numbers inside jsonb, cast: `.gt('meta->>score::int', 90)`.
+	* `eq` to `lte` also compare with another column (`db.col`) or the
+	* database time (`db.now`).
+	*
+	* @example
+	* .gt('age', 30)
+	* .lt('sent_per_hour', db.col('limit_per_hour'))
+	* .lt(db.col('sent_per_hour').ifNull(0), db.col('limit_per_hour'))
+	* .lte('client_sent_time', db.now().minus('1 hour'))
+	*/
+	gt(column, value) {
+		return this.#filter(column, "gt", value);
+	}
+	/** Greater than or equal. @example .gte('meta->>score::int', 90) */
+	gte(column, value) {
+		return this.#filter(column, "gte", value);
+	}
+	/** Less than. */
+	lt(column, value) {
+		return this.#filter(column, "lt", value);
+	}
+	/** Less than or equal. */
+	lte(column, value) {
+		return this.#filter(column, "lte", value);
+	}
+	/**
+	* SQL LIKE: `%` is any text, `_` is one character (escape with `\\_`).
+	*
+	* @example
+	* .like('name', 'user\\_1%')
+	*/
+	like(column, pattern) {
+		return this.#filter(column, "like", pattern);
+	}
+	/**
+	* Case-insensitive LIKE.
+	*
+	* @example
+	* .ilike('email', '%@example.com')
+	* .ilike('posts.comments.body', '%hello%')   // search a deeper related table
+	*/
+	ilike(column, pattern) {
+		return this.#filter(column, "ilike", pattern);
+	}
+	/** IS NULL / IS TRUE / IS FALSE. @example .is('deleted_at', null) */
+	is(column, value) {
+		return this.#filter(column, "is", value);
+	}
+	/** One of the values. @example .in('name', ['user_3', 'user_5']) */
+	in(column, values) {
+		return this.#filter(column, "in", values);
+	}
+	/**
+	* Has ALL of the values (arrays), or has these keys and values (jsonb objects).
+	*
+	* @example
+	* .contains('tags', ['one', 'two'])
+	* .contains('meta', { city: 'Dhaka', vip: true })
+	*/
+	contains(column, value) {
+		return this.#filter(column, "cs", value);
+	}
+	/**
+	* Has nothing outside the values.
+	*
+	* @example
+	* .containedBy('tags', ['one', 'two', 'three'])
+	*/
+	containedBy(column, value) {
+		return this.#filter(column, "cd", value);
+	}
+	/**
+	* Has ANY of the values. Works on jsonb/json arrays, jsonb paths and Postgres arrays.
+	*
+	* @example
+	* .overlaps('scores', ['one', 'three'])
+	* .overlaps('meta->tags', ['red', 'blue'])
+	*/
+	overlaps(column, values) {
+		return this.#filter(column, "ov", values);
+	}
+	/** Any filter by name: `.filter('age', 'gte', 30)`. */
+	filter(column, op, value) {
+		return this.#filter(column, op, value);
+	}
+	/**
+	* Equal on every key.
+	*
+	* @example
+	* .match({ active: true, age: 30 })
+	*/
+	match(values) {
+		for (const [k, v] of Object.entries(values)) this.eq(k, v);
+		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
+	* .or((q) => q.gt('age', 30).eq('meta->>city', 'Dhaka'))   // age > 30 OR city = 'Dhaka'
+	* .or((q) => q.eq('role', 'admin').and((q) => q.gte('age', 18).is('verified', true)))
+	* .or((q) => q.eq('posts.published', true).gt('posts.likes', 10))   // filters the related posts
+	*/
+	or(conditions) {
+		return this.#group("or", conditions);
+	}
+	/**
+	* All of the conditions, as one group. Mostly useful inside `or()`.
+	*
+	* @example
+	* .or((q) => q.eq('role', 'admin').and((q) => q.gte('age', 18).eq('active', true)))
+	*/
+	and(conditions) {
+		return this.#group("and", conditions);
+	}
+	not(a, op, value) {
+		if (typeof a === "function") return this.#group("not", a);
+		return this.#group("not", (q) => q.filter(a, op, value));
+	}
+	#group(group, conditions) {
+		const q = new FilterGroup();
+		conditions(q);
+		if (q.problem) this.problem ??= q.problem;
+		this.push({
+			group,
+			filters: q.filters
+		});
+		return this;
+	}
+};
+/**
+* The conditions inside `or()`, `and()` or `not()`: every filter method, plus
+* nested groups. Chain them on `q`; the callback's return value is ignored.
+*/
+var FilterGroup = class extends Filters {
+	/** @internal */ filters = [];
+	/** @internal */
+	push(filter) {
+		this.filters.push(filter);
+	}
+};
+/**
+* What reads and writes share: filters, step names and sending. Awaiting a
+* builder sends the request and resolves to `{ data, error, count, status }`;
+* it never throws. `T` is the row type, `R` the type of `data`.
+*/
+var Builder = class extends Filters {
+	/** @internal */ transport;
+	/** @internal */ req;
+	#name;
+	/** @internal */
+	constructor(transport, req, name, problem) {
+		super();
+		this.transport = transport;
+		this.req = req;
+		this.#name = name;
+		this.problem = problem;
+	}
+	/** @internal */
+	push(filter) {
+		this.req.filters.push(filter);
+	}
+	/**
+	* Name a step in the array form of `transaction()`, so later steps can use
+	* its rows with `tx.ref('name.column')`. (In the object form the key is the name.)
+	*
+	* @example
+	* db.transaction((tx) => [
+	*   tx.from('posts').insert({ title, user_id }).returning('id').as('post'),
+	*   tx.from('comments').insert({ post_id: tx.ref('post.id'), body, author_id }),
+	* ])
+	*/
+	as(name) {
+		this.#name = name;
+		return this;
+	}
+	/** @internal The `.as()` name, if any. */
+	stepName() {
+		return this.#name;
+	}
+	/** @internal A problem found while building, reported instead of sending. */
+	invalid() {
+		return this.problem;
+	}
+	/** @internal The request as sent to POST /query. */
+	request() {
+		return this.req;
+	}
+	/** @internal The request as sent to the server. */
+	toStep() {
+		return this.#name ? {
+			name: this.#name,
+			...this.req
+		} : { ...this.req };
+	}
+	then(onfulfilled, onrejected) {
+		const run = async () => {
+			const invalid = this.invalid();
+			if (invalid) return {
+				data: null,
+				error: { message: invalid },
+				count: null,
+				status: 0
+			};
+			if (!this.transport) return {
+				data: null,
+				error: { message: "this query belongs to a transaction: return it from the transaction callback instead of awaiting it" },
+				count: null,
+				status: 0
+			};
+			return this.transport.post("/query", this.request());
+		};
+		return run().then(onfulfilled, onrejected);
+	}
+};
+/**
+* Supabase-style query builder. Reads use `select()` and its modifiers;
+* `insert()` / `upsert()` / `update()` / `delete()` turn it into a
+* {@link WriteBuilder}. See GUIDE.md for recipes.
+*
+* @example
+* const { data, error } = await db.from('users').select('id, name').eq('active', true).random().limit(5)
+*/
+var QueryBuilder = class extends Builder {
+	#single = false;
+	#defaultReadFrom;
+	/** @internal Use `client.from()` or `tx.from()`. */
+	constructor(transport, table, readFrom) {
+		super(transport, {
+			table,
+			action: "select",
+			columns: "*",
+			filters: [],
+			order: [],
+			returning: false,
+			count: false
+		});
+		this.#defaultReadFrom = readFrom;
+	}
+	/**
+	* Columns to return. `'*'` (the default) means all. Supports aliases, jsonb
+	* paths, casts, related tables and related counts.
+	*
+	* `{ count: 'exact' }` also fills `count`; add `head: true` to skip the rows.
+	*
+	* @example
+	* db.from('users').select()                                  // all columns
+	* db.from('users').select('id, fullName:name, city:meta->>city, score:meta->>score::int')
+	* db.from('posts').select('title, author:users!user_id(name), comments(body), labels(name)')
+	* 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 = "*", ...extra) {
+		this.req.columns = columns;
+		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;
+	}
+	/**
+	* Number of matching rows: `data` is the number. All filters apply, including
+	* jsonb paths and `relation.column` filters on `!inner` relations.
+	*
+	* @example
+	* const { data: total } = await db.from('users').count()                       // 100
+	* const { data: active } = await db.from('users').eq('active', true).count()   // 75
+	*/
+	count(options = {}) {
+		if (options.distinct) return this.#aggregate("count", options.distinct, true);
+		this.req.countOnly = true;
+		return this;
+	}
+	/**
+	* Smallest value of a column over the matching rows: `data` is that value,
+	* or `null` when no rows match. `max`, `sum` and `avg` work the same way.
+	*
+	* @example
+	* const { data: first } = await db.from('posts').eq('user_id', id).min('created_at')
+	*/
+	min(column) {
+		return this.#aggregate("min", column);
+	}
+	/** Largest value. @example .eq('email', email).max('created_at') */
+	max(column) {
+		return this.#aggregate("max", column);
+	}
+	/** Sum of a number column, `null` when no rows match. */
+	sum(column) {
+		return this.#aggregate("sum", column);
+	}
+	/** Average of a number column, `null` when no rows match. */
+	avg(column) {
+		return this.#aggregate("avg", column);
+	}
+	#aggregate(fn, column, distinct) {
+		this.req.aggregate = distinct ? {
+			fn,
+			column,
+			distinct
+		} : {
+			fn,
+			column
+		};
+		return this;
+	}
+	/**
+	* Group rows for aggregates in `select()`: `count()`, `sum(col)`, `avg(col)`,
+	* `min(col)`, `max(col)`, `count(distinct col)`. Every plain column in the
+	* select must be grouped. `order()` can use an aggregate's name.
+	*
+	* @example
+	* db.from('posts').select('user_id, n:count(), last:max(created_at)').groupBy('user_id').order('n', { ascending: false })
+	*/
+	groupBy(columns) {
+		this.req.groupBy = columns.split(",").map((c) => c.trim()).filter(Boolean);
+		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
+	* db.from('posts').select('user_id').distinct()
+	*/
+	distinct() {
+		this.req.distinct = true;
+		return this;
+	}
+	/**
+	* Insert one or more rows. Values may contain `rel.*` to write related rows
+	* in the same transaction. Add `.returning()` to get the new rows back.
+	*
+	* @example
+	* await db.from('users').insert({ name, email })                      // data: null, count: 1
+	* const { data } = await db.from('users').insert({ name, email }).returning('id')  // [{ id }]
+	* await db.from('posts').insert({ title, user_id, comments: rel.create([{ body, author_id }]) })
+	*/
+	insert(values) {
+		return this.#write("insert", Array.isArray(values) ? values : [values]);
+	}
+	/**
+	* Insert rows, or handle an existing row with the same `onConflict` key
+	* (needs a unique constraint; default: primary key): update it, or with
+	* `ignoreDuplicates: true` return it unchanged (find-or-create). `merge`
+	* picks which columns change and how. Up to 5,000 rows per call, each key
+	* at most once.
+	*
+	* @example
+	* // find-or-create
+	* const { data } = await db.from('users')
+	*   .upsert({ email, name }, { onConflict: 'email', ignoreDuplicates: true })
+	*   .returning('id')
+	* data[0].id
+	* // insert or update
+	* await db.from('users').upsert({ email, name }, { onConflict: 'email' })
+	* // many rows: add the counters, set the rest
+	* await db.from('posts_stats').upsert(rows, {
+	*   onConflict: 'post_id',
+	*   merge: { views: 'add', likes: 'add', last_viewer_id: 'set' },
+	* })
+	*/
+	upsert(rows, options = {}) {
+		const { onConflict } = conflict(options.onConflict);
+		const { merge } = options;
+		return this.#write("insert", Array.isArray(rows) ? rows : [rows], {
+			upsert: true,
+			...options.ignoreDuplicates && { ignoreDuplicates: true },
+			...onConflict && { onConflict },
+			...merge && { merge: Array.isArray(merge) ? Object.fromEntries(merge.map((c) => [c, "set"])) : merge }
+		});
+	}
+	/**
+	* Update every matching row (needs at least one filter). Values may be plain
+	* (full replace), `ops.*` (atomic change) or `rel.*` (related rows).
+	*
+	* @example
+	* await db.from('users').update({ name: 'New' }).eq('id', id)
+	* await db.from('users').update({ scores: ops.append(4), age: ops.increment() }).eq('id', id).returning('age')
+	* await db.from('posts').update({ labels: rel.set([labelId]) }).eq('id', postId)
+	*/
+	update(values) {
+		return this.#write("update", [values]);
+	}
+	/**
+	* Delete every matching row (needs at least one filter).
+	*
+	* @example
+	* await db.from('posts').delete().eq('id', postId)
+	* await db.from('posts').delete().eq('id', postId).returning('title')  // the deleted rows
+	*/
+	delete() {
+		return this.#write("delete", void 0);
+	}
+	#write(action, values, extra = {}, problem) {
+		const { readFrom, ...rest } = this.req;
+		const req = {
+			...rest,
+			...extra,
+			action,
+			columns: "*"
+		};
+		if (values) req.values = values;
+		if (readFrom === "replica") problem ??= `replica() only works with select(); ${action} always runs on the primary`;
+		return new WriteBuilder(this.transport, req, this.stepName(), problem ?? this.invalid());
+	}
+	/**
+	* Let this read run on a read replica. Replicas can be a moment behind the
+	* primary, so use it where slightly stale rows are fine (lists, search,
+	* counts), not right after writing the rows you read. Without a healthy
+	* replica on the server it reads from the primary. Reads only, not inside
+	* a transaction.
+	*
+	* @example
+	* await db.from('posts').select('title').eq('published', true).replica()
+	*/
+	replica() {
+		this.req.readFrom = "replica";
+		return this;
+	}
+	/**
+	* Read from the primary, overriding `createClient(..., { readFrom: 'replica' })`.
+	*
+	* @example
+	* await db.from('users').select().eq('id', id).primary()   // just wrote it: read your own write
+	*/
+	primary() {
+		this.req.readFrom = "primary";
+		return this;
+	}
+	/** @internal Applies the client's readFrom default to reads. */
+	request() {
+		if (this.req.readFrom || !this.#defaultReadFrom) return this.req;
+		return {
+			...this.req,
+			readFrom: this.#defaultReadFrom
+		};
+	}
+	/**
+	* Sort. Chain several: they apply in the order written. Ascending by default.
+	* With `referencedTable` it sorts the rows inside a relation.
+	*
+	* @example
+	* .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,
+			nullsFirst,
+			table: embedOf(options)
+		});
+		return this;
+	}
+	/**
+	* Random order. After other `order()` calls it only shuffles ties. With a
+	* `seed` the order is stable (same seed, same order), so `range()` pages never
+	* repeat or skip rows.
+	*
+	* @example
+	* .random().limit(5)                                  // 5 random rows
+	* .order('active', { ascending: false }).random()     // active first, each group shuffled
+	* .random({ seed: sessionId }).range(10, 19)          // stable page 2
+	* .random({ referencedTable: 'posts' }).limit(3, { referencedTable: 'posts' })  // 3 random posts each
+	*/
+	random(options = {}) {
+		const seed = options.seed === void 0 ? void 0 : String(options.seed);
+		this.req.order.push({
+			random: true,
+			seed,
+			table: embedOf(options)
+		});
+		return this;
+	}
+	/**
+	* At most `count` rows: always an array, `[]` when none match, even for
+	* `limit(1)`. With `referencedTable`, at most `count` related rows per parent.
+	*
+	* @example
+	* .limit(10)
+	* .limit(3, { referencedTable: 'posts' })
+	*/
+	limit(count, options = {}) {
+		const embed = embedOf(options);
+		if (embed) this.req.embedLimits = {
+			...this.req.embedLimits,
+			[embed]: count
+		};
+		else this.req.limit = count;
+		return this;
+	}
+	/**
+	* Rows `from` to `to`, inclusive, 0-based.
+	*
+	* @example
+	* .range(0, 9)    // page 1
+	* .range(10, 19)  // page 2
+	*/
+	range(from, to) {
+		this.req.offset = from;
+		this.req.limit = to - from + 1;
+		return this;
+	}
+	/**
+	* One row: `data` is that row as an object, or `null` when nothing matches
+	* (not an error). Adds `LIMIT 1`, so don't combine it with `limit()` or
+	* `range()`. With several matches it is the first in your `order()`.
+	*
+	* @example
+	* const { data: user } = await db.from('users').select().eq('id', id).single()
+	* if (!user) { ... }
+	* const { data: email } = await db.from('emails').select().eq('status', 'active').random().single()
+	*/
+	single() {
+		this.#single = true;
+		this.req.single = "single";
+		return this;
+	}
+	/** @internal */
+	invalid() {
+		if (this.problem) return this.problem;
+		if (this.#single && (this.req.limit !== void 0 || this.req.offset !== void 0)) return "single() already means one row: don't combine it with limit() or range()";
+	}
+};
+/**
+* An insert, upsert, update or delete. Like Postgres, it writes every
+* matching row; `data` is `null` and `count` the number of rows written,
+* unless `returning()` asks for the rows.
+*/
+var WriteBuilder = class extends Builder {
+	/**
+	* Return the written rows, like Postgres `RETURNING`: always an array (one
+	* row is `[row]`, none is `[]`). Takes `'*'` (the default) or column names.
+	*
+	* @example
+	* await db.from('users').insert({ name, email }).returning()               // [{ id, name, email, ... }]
+	* await db.from('users').update({ age: ops.increment() }).eq('id', id).returning('id, age')
+	* await db.from('posts').delete().eq('user_id', id).returning('id')       // every deleted row
+	*/
+	returning(columns = "*") {
+		this.req.columns = columns;
+		this.req.returning = true;
+		return this;
+	}
+};
+// src/ops.ts
+/**
+* Atomic update operator, applied by Postgres to the current column value.
+*
+*   update({ scores: ops.append(4), meta: ops.merge({ vip: true }), age: ops.increment() })
+*/
+var Op = class Op {
+	$op;
+	values;
+	path;
+	constructor(op, values, path = []) {
+		this.$op = op;
+		this.values = values;
+		this.path = path;
+	}
+	/** Apply at a JSON path inside a json/jsonb column: `ops.append('x').at('address', 'lines')`. */
+	at(...path) {
+		return new Op(this.$op, this.values, path.map(String));
+	}
+};
+const ops = {
+	/**
+	* Add values at the end of a jsonb array or Postgres array. An array argument is added as one element.
+	* @example
+	* update({ scores: ops.append(4) })                 // [1,2,3] -> [1,2,3,4]
+	* update({ meta: ops.append('y').at('tags') })      // inside a jsonb object
+	*/
+	append: (...values) => new Op("append", values),
+	/**
+	* Add values at the start of a jsonb array or Postgres array.
+	* @example
+	* update({ scores: ops.prepend(0) })                // [1,2,3] -> [0,1,2,3]
+	*/
+	prepend: (...values) => new Op("prepend", values),
+	/**
+	* Remove every element equal to one of the values.
+	* @example
+	* update({ scores: ops.remove(2) })                 // [1,2,3] -> [1,3]
+	*/
+	remove: (...values) => new Op("remove", values),
+	/**
+	* Shallow-merge keys into a json/jsonb object.
+	* @example
+	* update({ meta: ops.merge({ vip: true }) })        // {a:1} -> {a:1,vip:true}
+	*/
+	merge: (object) => new Op("merge", [object]),
+	/**
+	* Set a value at a JSON path (needs `.at(...)`); a number is an array position.
+	* @example
+	* update({ meta: ops.set('Lisbon').at('city') })
+	* update({ scores: ops.set(9).at(0) })              // [1,2,3] -> [9,2,3]
+	*/
+	set: (value) => new Op("set", [value]),
+	/**
+	* Remove the key (or array position) at a JSON path (needs `.at(...)`).
+	* @example
+	* update({ meta: ops.unset().at('vip') })
+	* update({ scores: ops.unset().at(0) })             // [1,2,3] -> [2,3]
+	*/
+	unset: () => new Op("unset", []),
+	/**
+	* Add to a number column, or to a number at a JSON path (negative to subtract).
+	* @example
+	* update({ age: ops.increment() })
+	* update({ meta: ops.increment(5).at('points') })
+	*/
+	increment: (by = 1) => new Op("increment", [by])
+};
+// src/client.ts
+const fail = (message) => ({
+	data: null,
+	error: { message },
+	count: null,
+	status: 0
+});
+function stepProblem(s) {
+	if (s.toStep().readFrom === "replica") return "transaction steps always run on the primary: drop replica()";
+	return s.invalid();
+}
+/** Turn the callback's result into wire steps; null + message when it is not usable. */
+function toSteps(steps) {
+	if (Array.isArray(steps)) {
+		if (steps.length === 0) return "transaction callback must return a non-empty array or object of steps";
+		for (const s of steps) {
+			if (!(s instanceof QueryBuilder || s instanceof WriteBuilder)) return "every transaction step must be tx.from(...)";
+			const bad = stepProblem(s);
+			if (bad) return bad;
+		}
+		return {
+			names: null,
+			wire: steps.map((s) => s.toStep())
+		};
+	}
+	if (steps && typeof steps === "object") {
+		const entries = Object.entries(steps);
+		if (entries.length === 0) return "transaction callback must return a non-empty array or object of steps";
+		for (const [name, s] of entries) {
+			if (/^(0|[1-9]\d*)$/.test(name)) return `step name "${name}" looks like a number; use a word (JavaScript reorders number keys)`;
+			if (name.includes(".")) return `step name "${name}" must not contain a dot (refs use name.column)`;
+			if (!(s instanceof QueryBuilder || s instanceof WriteBuilder)) return `step "${name}" must be tx.from(...)`;
+			if (s.stepName()) return `step "${name}" already has a name; drop .as("${s.stepName()}") in the object form`;
+			const bad = stepProblem(s);
+			if (bad) return bad;
+		}
+		return {
+			names: entries.map(([n]) => n),
+			wire: entries.map(([name, s]) => ({
+				...s.toStep(),
+				name
+			}))
+		};
+	}
+	return "transaction callback must return an array or object of steps";
+}
+function createTransport(url, apiKey, options) {
+	const base = url.replace(/\/+$/, "");
+	const fetchImpl = options.fetch ?? globalThis.fetch;
+	if (!fetchImpl) throw new Error("arn-db: no fetch available; pass options.fetch (Node 18+ has a global fetch)");
+	if (typeof apiKey !== "string" || apiKey === "") throw new Error("arn-db: createClient(url, apiKey) needs an API key");
+	return { async post(path, body) {
+		let res;
+		try {
+			res = await fetchImpl(base + path, {
+				method: "POST",
+				headers: {
+					...options.headers,
+					"Content-Type": "application/json",
+					apikey: apiKey
+				},
+				body: JSON.stringify(body)
+			});
+		} catch (err) {
+			return {
+				data: null,
+				error: { message: err.message },
+				count: null,
+				status: 0
+			};
+		}
+		let json;
+		try {
+			json = await res.json();
+		} catch {
+			return {
+				data: null,
+				error: { message: `invalid response (HTTP ${res.status})` },
+				count: null,
+				status: res.status
+			};
+		}
+		if (json.error) return {
+			data: null,
+			error: json.error,
+			count: null,
+			status: res.status
+		};
+		return {
+			data: json.data ?? null,
+			error: null,
+			count: json.count ?? null,
+			status: res.status
+		};
+	} };
+}
+/**
+* Server-side client for the Go API (it refuses browser requests). Every call
+* resolves to `{ data, error, count, status }` and never throws.
+*
+* @example
+* const db = createClient(process.env.PG_API_URL!, process.env.PG_API_KEY!)
+* const { data, error } = await db.from('users').select().eq('active', true)
+*/
+function createClient(url, apiKey, options = {}) {
+	const transport = createTransport(url, apiKey, options);
+	const { readFrom } = options;
+	if (readFrom !== void 0 && readFrom !== "primary" && readFrom !== "replica") throw new Error(`arn-db: readFrom must be 'primary' or 'replica', got ${JSON.stringify(readFrom)}`);
+	return {
+		from: (table) => new QueryBuilder(transport, table, readFrom),
+		ops,
+		rel,
+		col,
+		now,
+		raw,
+		async transaction(build) {
+			const steps = toSteps(build({
+				from: (table) => new QueryBuilder(null, table),
+				ref: (path) => ({ $ref: path }),
+				ops,
+				rel,
+				col,
+				now,
+				raw
+			}));
+			if (typeof steps === "string") return fail(steps);
+			const res = await transport.post("/transaction", { steps: steps.wire });
+			if (res.error || !steps.names) return res;
+			const results = res.data;
+			const byName = Object.fromEntries(steps.names.map((n, i) => [n, results[i]]));
+			return {
+				...res,
+				data: byName
+			};
+		}
+	};
+}
+// src/env.ts
+let client;
+/** 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 {}
+	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)");
+	if (!key) throw new Error("arn-db: set ARN_DB_KEY or use createClient(url, key)");
+	client = createClient(url, key);
+	return client;
+}
+/**
+* Ready-made client from the environment: `ARN_DB_URL` (e.g.
+* `https://your-api.example.com/v2/raw`) and `ARN_DB_KEY`, read on the first query,
+* with `./.env` loaded if they are not set yet. A missing variable throws on
+* that first query. Use `createClient()` for other keys or options.
+*
+* @example
+* import { db } from 'arn-db'
+* const { data, error } = await db.from('users').select().eq('id', id).single()
+*/
+const db = {
+	from: (table) => envClient().from(table),
+	transaction: ((build) => envClient().transaction(build)),
+	ops,
+	rel,
+	col,
+	now,
+	raw
+};
+exports.Col = Col;
+exports.FilterGroup = FilterGroup;
+exports.Now = Now;
+exports.Op = Op;
+exports.QueryBuilder = QueryBuilder;
+exports.Raw = Raw;
+exports.WriteBuilder = WriteBuilder;
+exports.col = col;
+exports.createClient = createClient;
+exports.db = db;
+exports.now = now;
+exports.ops = ops;
+exports.raw = raw;
+exports.rel = rel;
+
+//# sourceMappingURL=index.cjs.map