arn-db 0.0.0-stage → 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,899 @@
+/**
+ * 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'))
+ */
+export declare class Col {
+  #private;
+  readonly name: string;
+  constructor(name: string, ifNull?: {
+    value: unknown;
+  });
+  /** Use `value` where the column is NULL: `COALESCE(column, value)`. */
+  ifNull(value: unknown): Col;
+  /** @internal The NULL replacement, if any. */
+  nullValue(): {
+    value: unknown;
+  } | undefined;
+  /** @internal Wire format. */
+  toJSON(): {
+    $col: string;
+    ifNull?: unknown;
+  };
+}
+/**
+ * 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() })
+ */
+export declare class Now {
+  #private;
+  constructor(interval?: string);
+  /** Later by `interval`: `db.now().plus('1 day')`. */
+  plus(interval: string): Now;
+  /** Earlier by `interval`: `db.now().minus('1 hour')`. */
+  minus(interval: string): Now;
+  /** @internal Wire format. */
+  toJSON(): {
+    $now: true;
+    interval?: string;
+  };
+}
+/** A filter's column: a name, or `db.col(name).ifNull(value)`. */
+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.
+ *
+ *   update({ scores: ops.append(4), meta: ops.merge({ vip: true }), age: ops.increment() })
+ */
+export declare class Op {
+  readonly $op: string;
+  readonly values: unknown[];
+  readonly path: string[];
+  constructor(op: string, values: unknown[], path?: string[]);
+  /** Apply at a JSON path inside a json/jsonb column: `ops.append('x').at('address', 'lines')`. */
+  at(...path: (string | number)[]): Op;
+}
+export declare 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: unknown[]) => Op;
+  /**
+   * 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: unknown[]) => Op;
+  /**
+   * Remove every element equal to one of the values.
+   * @example
+   * update({ scores: ops.remove(2) })                 // [1,2,3] -> [1,3]
+   */
+  remove: (...values: unknown[]) => Op;
+  /**
+   * Shallow-merge keys into a json/jsonb object.
+   * @example
+   * update({ meta: ops.merge({ vip: true }) })        // {a:1} -> {a:1,vip:true}
+   */
+  merge: (object: Row) => Op;
+  /**
+   * 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: unknown) => Op;
+  /**
+   * 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: () => Op;
+  /**
+   * 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?: number) => Op;
+};
+/** A table row. Pass your own row type to `from<T>()` for typed results. */
+type Row = Record<string, any>;
+interface PgError {
+  message: string;
+  /** Postgres SQLSTATE, e.g. "23505" for a unique violation. */
+  code?: string;
+  details?: string;
+  /** Failing step index (0-based) when a transaction fails. */
+  step?: number;
+  /** That step's `.as()` name, if any. */
+  stepName?: string;
+}
+type QueryResult<R> = {
+  data: R;
+  error: null;
+  count: number | null;
+  status: number;
+} | {
+  data: null;
+  error: PgError;
+  count: null;
+  status: number;
+};
+type FilterOp = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ilike' | 'is' | 'in' | 'cs' | 'cd' | 'ov';
+/** One condition: `column op value`. */
+interface ConditionFilter {
+  column: string;
+  op: FilterOp;
+  value: unknown;
+  /** Compare `COALESCE(column, ifNull)` instead of the column. */
+  ifNull?: unknown;
+}
+/** Conditions joined with AND (`and`, `not`) or OR (`or`); `not` negates the group. */
+interface GroupFilter {
+  group: 'and' | 'or' | 'not';
+  filters: Filter[];
+}
+/** 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;
+  seed?: string;
+  /** Embed name or alias; omitted for the main table. */
+  table?: string;
+}
+/** Wire format of one request to the Go server. */
+interface QueryRequest {
+  table: string;
+  action: 'select' | 'insert' | 'update' | 'delete';
+  columns: string;
+  filters: Filter[];
+  order: Order[];
+  limit?: number;
+  offset?: number;
+  embedLimits?: Record<string, number>;
+  values?: Row[];
+  returning: boolean;
+  count: boolean;
+  head?: boolean;
+  countOnly?: boolean;
+  single?: 'single';
+  skipLocked?: boolean;
+  upsert?: boolean;
+  onConflict?: string[];
+  ignoreDuplicates?: boolean;
+  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;
+    column: string;
+    distinct?: boolean;
+  };
+  readFrom?: ReadFrom;
+}
+type AggregateFn = 'count' | 'sum' | 'avg' | 'min' | 'max';
+/**
+ * How `upsert()`'s `merge` changes a column of an existing row:
+ * `'set'` the incoming value, `'add'` stored + incoming (NULL counts as 0),
+ * `'append'` / `'prepend'` join stored and incoming jsonb or Postgres arrays.
+ */
+type MergeMode = 'set' | 'add' | 'append' | 'prepend';
+/** Where a read runs: the primary, or a read replica when the server has one. */
+type ReadFrom = 'primary' | 'replica';
+interface UpsertOptions {
+  /** Columns with a unique constraint that identify the row, e.g. `'email'` or `'user_id,title'`. Default: primary key. */
+  onConflict?: string;
+  /**
+   * `true`: find-or-create. An existing row is left unchanged and returned.
+   * `false` (default): insert, or update the existing row with these values.
+   */
+  ignoreDuplicates?: boolean;
+  /**
+   * 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, 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 | 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 {
+  referencedTable?: string;
+  /** Older supabase-js name for `referencedTable`. */
+  foreignTable?: string;
+}
+interface Transport {
+  post(path: string, body: unknown): Promise<QueryResult<any>>;
+}
+/** One step of a transaction, as sent to the server. */
+interface TxStepRequest extends QueryRequest {
+  name?: string;
+}
+/** 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;
+  /**
+   * 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: Column, value: unknown): this;
+  /** Not equal. */
+  neq(column: Column, value: unknown): this;
+  /**
+   * 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: Column, value: unknown): this;
+  /** Greater than or equal. @example .gte('meta->>score::int', 90) */
+  gte(column: Column, value: unknown): this;
+  /** Less than. */
+  lt(column: Column, value: unknown): this;
+  /** Less than or equal. */
+  lte(column: Column, value: unknown): this;
+  /**
+   * SQL LIKE: `%` is any text, `_` is one character (escape with `\\_`).
+   *
+   * @example
+   * .like('name', 'user\\_1%')
+   */
+  like(column: string, pattern: string): this;
+  /**
+   * Case-insensitive LIKE.
+   *
+   * @example
+   * .ilike('email', '%@example.com')
+   * .ilike('posts.comments.body', '%hello%')   // search a deeper related table
+   */
+  ilike(column: string, pattern: string): this;
+  /** IS NULL / IS TRUE / IS FALSE. @example .is('deleted_at', null) */
+  is(column: Column, value: null | boolean): this;
+  /** One of the values. @example .in('name', ['user_3', 'user_5']) */
+  in(column: string, values: readonly unknown[]): this;
+  /**
+   * 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: string, value: unknown): this;
+  /**
+   * Has nothing outside the values.
+   *
+   * @example
+   * .containedBy('tags', ['one', 'two', 'three'])
+   */
+  containedBy(column: string, value: unknown): this;
+  /**
+   * 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: string, values: readonly unknown[]): this;
+  /** Any filter by name: `.filter('age', 'gte', 30)`. */
+  filter(column: Column, op: FilterOp, value: unknown): this;
+  /**
+   * Equal on every key.
+   *
+   * @example
+   * .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.
+   *
+   * @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: (q: FilterGroup) => unknown): this;
+  /**
+   * 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: (q: FilterGroup) => unknown): this;
+  /**
+   * Not all of the conditions: `NOT (a AND b)`. Like Postgres, NULL is neither
+   * true nor false: a row with a null `age` matches neither `.gt('age', 30)`
+   * nor `.not('age', 'gt', 30)`.
+   *
+   * @example
+   * .not('deleted_at', 'is', null)
+   * .not((q) => q.eq('meta->>city', 'Tokyo').lt('age', 30))
+   * .not((q) => q.or((q) => q.eq('a', 1).eq('b', 2)))   // neither a = 1 nor b = 2
+   */
+  not(conditions: (q: FilterGroup) => unknown): this;
+  not(column: Column, op: FilterOp, value: unknown): 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.
+ */
+export declare class FilterGroup extends Filters {
+  /** @internal */ readonly filters: Filter[];
+  /** @internal */
+  protected push(filter: Filter): void;
+}
+/**
+ * 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`.
+ */
+declare abstract class Builder<T extends Row, R> extends Filters implements PromiseLike<QueryResult<R>> {
+  #private;
+  /** @internal */ protected readonly transport: Transport | null;
+  /** @internal */ protected readonly req: QueryRequest;
+  /** @internal */
+  constructor(transport: Transport | null, req: QueryRequest, name?: string, problem?: string);
+  /** @internal */
+  protected push(filter: Filter): void;
+  /**
+   * 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: string): this;
+  /** @internal The `.as()` name, if any. */
+  stepName(): string | undefined;
+  /** @internal A problem found while building, reported instead of sending. */
+  invalid(): string | undefined;
+  /** @internal The request as sent to POST /query. */
+  protected request(): QueryRequest;
+  /** @internal The request as sent to the server. */
+  toStep(): TxStepRequest;
+  then<A = QueryResult<R>, B = never>(onfulfilled?: ((value: QueryResult<R>) => A | PromiseLike<A>) | null, onrejected?: ((reason: unknown) => B | PromiseLike<B>) | null): PromiseLike<A | B>;
+}
+/**
+ * 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)
+ */
+export declare class QueryBuilder<T extends Row = Row, R = T[]> extends Builder<T, R> {
+  #private;
+  /** @internal Use `client.from()` or `tx.from()`. */
+  constructor(transport: Transport | null, table: string, readFrom?: 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?: 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.
+   *
+   * @example
+   * const { data: total } = await db.from('users').count()                       // 100
+   * const { data: active } = await db.from('users').eq('active', true).count()   // 75
+   */
+  count(options?: {
+    distinct?: string;
+  }): QueryBuilder<T, number>;
+  /**
+   * 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<V = any>(column: string): QueryBuilder<T, V | null>;
+  /** Largest value. @example .eq('email', email).max('created_at') */
+  max<V = any>(column: string): QueryBuilder<T, V | null>;
+  /** Sum of a number column, `null` when no rows match. */
+  sum(column: string): QueryBuilder<T, number | null>;
+  /** Average of a number column, `null` when no rows match. */
+  avg(column: string): QueryBuilder<T, number | null>;
+  /**
+   * 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: 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`.
+   *
+   * @example
+   * db.from('posts').select('user_id').distinct()
+   */
+  distinct(): 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: Row | Row[]): WriteBuilder<T>;
+  /**
+   * 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: Row | Row[], options?: UpsertOptions): WriteBuilder<T>;
+  /**
+   * 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: Row): WriteBuilder<T>;
+  /**
+   * 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(): WriteBuilder<T>;
+  /**
+   * 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;
+  /**
+   * 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;
+  /** @internal Applies the client's readFrom default to reads. */
+  protected request(): QueryRequest;
+  /**
+   * 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: string | Raw, options?: {
+    ascending?: boolean;
+    nullsFirst?: boolean;
+  } & ReferencedTableOption): 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?: ReferencedTableOption & {
+    seed?: string | number;
+  }): 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: number, options?: ReferencedTableOption): this;
+  /**
+   * Rows `from` to `to`, inclusive, 0-based.
+   *
+   * @example
+   * .range(0, 9)    // page 1
+   * .range(10, 19)  // page 2
+   */
+  range(from: number, to: number): 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(): QueryBuilder<T, T | null>;
+  /** @internal */
+  invalid(): string | undefined;
+}
+/**
+ * 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.
+ */
+export declare class WriteBuilder<T extends Row = Row, R = null> extends Builder<T, R> {
+  /**
+   * 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?: string): WriteBuilder<T, T[]>;
+}
+/** A related row's key: the value of a single-column key, or an object for composite keys. */
+type Key = string | number | Row;
+type RelOpName = 'create' | 'upsert' | 'connectOrCreate' | 'connect' | 'disconnect' | 'set' | 'update' | 'delete';
+/**
+ * A write to a related table, used as a value in `insert()` / `update()` under
+ * the related table's name (add `!fk_column` when there are several FKs):
+ *
+ *   insert({ title, comments: rel.create([{ body }]), labels: rel.connect([labelId]) })
+ *
+ * Everything in one insert()/update() runs in one transaction.
+ */
+interface RelOp {
+  readonly $rel: RelOpName;
+  readonly rows?: Row[];
+  readonly keys?: Key[];
+  readonly match?: Row;
+  readonly values?: Row;
+  readonly onConflict?: string[];
+}
+export declare 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: Row | Row[]) => RelOp;
+  /**
+   * 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: Row, options?: {
+    onConflict?: string;
+  }) => RelOp;
+  /**
+   * 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: Row, options?: {
+    onConflict?: string;
+  }) => RelOp;
+  /**
+   * 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: Key | Key[]) => RelOp;
+  /**
+   * 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?: Key | Key[]) => RelOp;
+  /**
+   * 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: Key[]) => RelOp;
+  /**
+   * 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: Row, values: Row) => RelOp;
+  /**
+   * 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?: Row) => RelOp;
+};
+interface ClientOptions {
+  /** Extra headers on every request. */
+  headers?: Record<string, string>;
+  /** Custom fetch (defaults to the global one, Node 18+). */
+  fetch?: typeof fetch;
+  /**
+   * Where reads run by default: `'primary'` (default) or `'replica'` (a read
+   * replica when the server has a healthy one, else the primary). Writes and
+   * transactions always use the primary. Override per query with
+   * `.replica()` / `.primary()`.
+   */
+  readFrom?: ReadFrom;
+}
+/** Placeholder for a value from an earlier transaction step. */
+interface Ref {
+  readonly $ref: string;
+}
+/** Any step a transaction accepts. */
+type Step = QueryBuilder<any, any> | WriteBuilder<any, any>;
+/** The `data` type of a step. */
+type StepData<S> = S extends PromiseLike<QueryResult<infer R>> ? R : never;
+interface Tx {
+  /** Start a step. Don't await it: return it from the transaction callback. */
+  from<T extends Row = Row>(table: string): QueryBuilder<T>;
+  /**
+   * A value from an earlier named step, usable in values and filters.
+   * A step that returned one row is read directly (`'post.id'`); with several
+   * rows, pick one: `tx.ref('posts.0.id')`.
+   *
+   * @example
+   * tx.from('comments').insert({ post_id: tx.ref('post.id'), body, author_id })
+   */
+  ref(path: string): Ref;
+  /** Atomic jsonb/array/number changes, same as `db.ops`. */
+  readonly ops: typeof ops;
+  /** Writes to related rows, same as `db.rel`. */
+  readonly rel: typeof rel;
+  /** Another column of the same row, same as `db.col`. */
+  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>;
+  /**
+   * Atomic jsonb/array/number changes for `update()` values (same as `import { ops }`).
+   *
+   * @example
+   * await db.from('users').update({ scores: db.ops.append(4), age: db.ops.increment() }).eq('id', id)
+   */
+  readonly ops: typeof ops;
+  /**
+   * Writes to related rows inside `insert()` / `update()` values (same as `import { rel }`).
+   *
+   * @example
+   * await db.from('posts').insert({ title, user_id, comments: db.rel.create([{ body, author_id }]) })
+   */
+  readonly rel: typeof rel;
+  /**
+   * Another column of the same row, for comparing two columns in a filter.
+   *
+   * @example
+   * await db.from('accounts').select().lt('sent_per_hour', db.col('limit_per_hour'))
+   * await db.from('accounts').select().lt(db.col('sent_per_hour').ifNull(0), db.col('limit_per_hour'))
+   */
+  readonly col: typeof col;
+  /**
+   * The database server's `now()`, optionally `.plus()` / `.minus()` one interval.
+   * Works in filters and in insert/update values.
+   *
+   * @example
+   * await db.from('clients').select().lte('sent_at', db.now().minus('1 hour'))
+   * 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.
+   *
+   * Return an object (keys name the steps; `data` has the same keys) or an
+   * array (name steps with `.as()`; `data` is an array). Don't await the steps.
+   *
+   * @example
+   * const { data, error } = await db.transaction((tx) => ({
+   *   user: tx.from('users').upsert({ email }, { onConflict: 'email', ignoreDuplicates: true }).returning('id'),
+   *   post: tx.from('posts').insert({ title, user_id: tx.ref('user.id') }).returning('id'),
+   *   total: tx.from('posts').eq('user_id', tx.ref('user.id')).count(),
+   * }))
+   * data.post[0].id   // returning() is always an array
+   */
+  transaction<S extends Record<string, Step>>(steps: (tx: Tx) => S): Promise<QueryResult<{ [K in keyof S]: StepData<S[K]>; }>>;
+  transaction<S extends Step[]>(steps: (tx: Tx) => [...S]): Promise<QueryResult<{ [K in keyof S]: StepData<S[K]>; }>>;
+}
+/**
+ * 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)
+ */
+export declare function createClient(url: string, apiKey: string, options?: ClientOptions): 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()
+ */
+export declare const db: Client;
+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