@aurabase/aurabase-js 0.3.0

package/packages/db/src/QueryBuilder.ts

@@ -0,0 +1,830 @@
+import type { AuraResponse, CountMode, AuraClientLike } from '@aurabase/core'
+import { fetchWithAuth, AuraError } from '@aurabase/core'
+import type { GetResult } from './select-query-parser/result'
+import type {
+  GenericSchema,
+  GenericTable,
+  GenericView,
+  ClientServerOptions,
+} from './pgrst-types/common/common'
+
+/**
+ * `ClientOptions` figé pour aurabase — PostgREST v12. Satisfait `ClientServerOptions`
+ * et sert de défaut au threading de types (pas de configuration exposée côté SDK).
+ */
+export type AuraClientOptionsT = { PostgrestVersion: '12' }
+
+interface StoredFilter {
+  column: string
+  op: string
+  value: unknown
+}
+
+/**
+ * Quote une valeur PostgREST contenant des caractères réservés (`,` `(` `)` `"`).
+ * Sans ça, une valeur comme `"Aix, FR"` dans un `in.(…)` serait lue comme deux valeurs.
+ * Les `"` internes sont doublés (échappement PostgREST).
+ */
+function quoteReserved(v: unknown): string {
+  const s = String(v)
+  return /[,()"]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s
+}
+
+/** Encode une valeur de filtre en fragment PostgREST `op.value` (gère array-syntax, jsonb, ranges). */
+function encodeFilterValue(op: string, value: unknown): string {
+  if (op === 'in' || op === 'not.in') {
+    const arr = Array.isArray(value) ? value : [value]
+    return `${op}.(${arr.map(quoteReserved).join(',')})`
+  }
+  if (op === 'cs' || op === 'cd' || op === 'ov') {
+    if (Array.isArray(value)) return `${op}.{${value.map(quoteReserved).join(',')}}`
+    if (value !== null && typeof value === 'object') return `${op}.${JSON.stringify(value)}`
+    return `${op}.${value}`
+  }
+  if (op.endsWith('(all)') || op.endsWith('(any)')) {
+    const arr = Array.isArray(value) ? value : [value]
+    return `${op}.{${arr.map(quoteReserved).join(',')}}`
+  }
+  return `${op}.${value}`
+}
+
+interface OrGroup {
+  filters: StoredFilter[]
+}
+
+/** En-tête PostgREST demandant un objet unique (parité postgrest-js `.single()`). */
+const PGRST_OBJECT_ACCEPT = 'application/vnd.pgrst.object+json'
+
+/**
+ * Détecte un 406 « 0 lignes » (vs « plusieurs lignes ») pour discriminer les deux cas
+ * de cardinalité de `single()`/`maybeSingle()`. Le gateway réécrit PGRST116 en code
+ * `NOT_SINGULAR` mais préserve le détail PostgREST « The result contains N rows » (imbriqué
+ * sous `error.details`). On cherche donc « 0 rows » dans message + détails sérialisés.
+ * `\b0 rows\b` évite un faux positif sur « 10 rows », « 20 rows », etc.
+ */
+function mentionsZeroRows(err: { message?: string; details?: unknown } | null): boolean {
+  if (!err) return false
+  const details = typeof err.details === 'string' ? err.details : JSON.stringify(err.details ?? '')
+  return /\b0 rows\b/.test(`${err.message ?? ''} ${details}`)
+}
+
+/** Construit l'erreur de cardinalité PGRST116 (parité postgrest-js/Supabase). */
+function pgrst116(zeroRows: boolean): AuraError {
+  return new AuraError(406, {
+    error: {
+      code: 'PGRST116',
+      message: zeroRows
+        ? 'JSON object requested, 0 rows returned'
+        : 'JSON object requested, multiple rows returned',
+    },
+  })
+}
+
+// `id` non-null → mode COMPAT id-based (route `/{basePath}/{id}`, rétro-compat) ;
+// `id: null` → mode FILTRÉ (route Table `/{basePath}?...` + filtres, parité PostgREST).
+type MutationMode =
+  | { type: 'insert'; body: unknown }
+  | { type: 'update'; id: string | null; body: unknown }
+  | { type: 'delete'; id: string | null }
+  | { type: 'upsert'; body: unknown; onConflict: string }
+
+/** État d'un builder en mode `rpc` (`DatabaseService.rpc()`) : args + verbe HTTP. */
+export type RpcMode = { args: unknown; verb: 'POST' | 'GET' | 'HEAD' }
+
+/**
+ * Base class : état partagé, constructeur, exécution HTTP (`then`/`_execute`),
+ * `throwOnError` et `buildQueryString`. Implements PromiseLike so it can be
+ * awaited directly.
+ */
+export class AuraPostgrestBuilder<
+  // `ClientOptions`/`ThrowOnError` sont des paramètres fantômes : ils portent la
+  // signature (parité postgrest-js) et le threading des sous-classes, sans affecter
+  // le runtime ni la forme d'`AuraResponse`.
+  ClientOptions extends ClientServerOptions = AuraClientOptionsT,
+  Result = Record<string, unknown>,
+  ThrowOnError extends boolean = false,
+> implements PromiseLike<AuraResponse<Result>>
+{
+  protected readonly _client: AuraClientLike
+  protected readonly _basePath: string
+  protected _filters: StoredFilter[] = []
+  protected _orGroups: OrGroup[] = []
+  protected _selectColumns: string[] | null = null
+  // `select()` a-t-il été appelé ? (distinct de `_selectColumns`, que `select('*')`
+  // remet à `null`) — sert à poser `Prefer: return=representation` sur une mutation
+  // même avec `select('*')`.
+  protected _selectInvoked = false
+  protected _sortColumn: string | null = null
+  protected _sortDirection: 'asc' | 'desc' = 'asc'
+  protected _limit: number | null = null
+  protected _offset: number | null = null
+  protected _cursor: string | null = null
+  protected _count: CountMode | null = null
+  protected _rawSelect = false
+  protected _single = false
+  protected _maybeSingle = false
+  protected _throwOnError = false
+  protected _mutation: MutationMode | null = null
+  protected _rpc: RpcMode | null = null
+
+  constructor(client: AuraClientLike, basePath: string) {
+    this._client = client
+    this._basePath = basePath
+  }
+
+  throwOnError(): this {
+    this._throwOnError = true
+    return this
+  }
+
+  /**
+   * Positionne l'état interne `rpc` (args + verbe HTTP) — méthode package-interne
+   * utilisée par `DatabaseService.rpc()` pour éviter un cast sur un champ `protected`.
+   *
+   * `count` accepte `'planned'` (parité stricte `RpcOptions`, cf. `DatabaseService.rpc`)
+   * en plus de `CountMode` (`@aurabase/core`, qui ne connaît que `exact`/`estimated` —
+   * package partagé, non modifié ici). Le cast vers `_count` reste sans risque runtime :
+   * `buildQueryString` sérialise la valeur telle quelle en query param `count=`.
+   */
+  _initRpc(args: unknown, verb: 'POST' | 'GET' | 'HEAD', count?: 'exact' | 'planned' | 'estimated'): this {
+    this._rpc = { args, verb }
+    if (count) this._count = count as CountMode
+    return this
+  }
+
+  // -- Query string builder ---------------------------------------------------
+
+  buildQueryString(): string {
+    const params = new URLSearchParams()
+
+    // Select (raw string preserves embed syntax with parentheses)
+    if (this._selectColumns && this._selectColumns.length > 0) {
+      params.set('select', this._rawSelect ? this._selectColumns[0]! : this._selectColumns.join(','))
+    }
+
+    // Filters: col=op.value (encodage centralisé)
+    for (const f of this._filters) {
+      params.append(f.column, encodeFilterValue(f.op, f.value))
+    }
+
+    // OR groups — PostgREST syntax: or=(col.op.val,col2.op.val2)
+    for (const group of this._orGroups) {
+      const parts = group.filters.map((f) => `${f.column}.${encodeFilterValue(f.op, f.value)}`)
+      params.append('or', `(${parts.join(',')})`)
+    }
+
+    // Sort
+    if (this._sortColumn) {
+      params.set('sort_by', this._sortColumn)
+      params.set('sort_order', this._sortDirection)
+    }
+
+    // Pagination
+    if (this._limit !== null) params.set('limit', String(this._limit))
+    if (this._offset !== null) params.set('offset', String(this._offset))
+    if (this._cursor !== null) params.set('cursor', this._cursor)
+
+    // Count
+    if (this._count) params.set('count', this._count)
+
+    // Args RPC en query params quand le verbe est GET (get:true) ou HEAD (head:true)
+    // — parité PostgREST/postgrest-js : args en query pour les deux verbes sans corps.
+    if (
+      this._rpc &&
+      (this._rpc.verb === 'GET' || this._rpc.verb === 'HEAD') &&
+      this._rpc.args &&
+      typeof this._rpc.args === 'object'
+    ) {
+      for (const [k, v] of Object.entries(this._rpc.args as Record<string, unknown>)) {
+        params.set(k, typeof v === 'string' ? v : JSON.stringify(v))
+      }
+    }
+
+    return params.toString()
+  }
+
+  // -- Execution via PromiseLike ----------------------------------------------
+
+  then<TResult1 = AuraResponse<Result>, TResult2 = never>(
+    onfulfilled?: ((value: AuraResponse<Result>) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+  ): Promise<TResult1 | TResult2> {
+    return this._execute().then(onfulfilled, onrejected)
+  }
+
+  private async _execute(): Promise<AuraResponse<Result>> {
+    let res: AuraResponse<Result>
+
+    // Parité postgrest-js : `single()`/`maybeSingle()` demandent un objet unique via l'en-tête
+    // Accept (et NON plus `limit=2`, qui casse sur les mutations filtrées). Fusionné avec les
+    // autres en-têtes (Prefer) dans chaque branche ci-dessous.
+    const acceptSingle: Record<string, string> | undefined = this._single
+      ? { Accept: PGRST_OBJECT_ACCEPT }
+      : undefined
+
+    if (this._rpc) {
+      const qs = this.buildQueryString()
+      const sep = qs ? '?' : ''
+      const url = `${this._client.baseUrl}${this._basePath}${sep}${qs}`
+      const init: { method: string; body?: unknown; headers?: Record<string, string> } =
+        this._rpc.verb === 'POST'
+          ? { method: 'POST', body: this._rpc.args, headers: acceptSingle }
+          : { method: this._rpc.verb, headers: acceptSingle }
+      res = await fetchWithAuth<Result>(url, init, this._client)
+    } else if (this._mutation) {
+      const m = this._mutation
+
+      // GARDE-FOU ANTI-WIPE : un update()/delete() en mode filtré SANS aucun
+      // filtre effacerait/modifierait toute la table (le gateway ne l'empêche
+      // pas). On refuse AVANT tout appel réseau. Le mode compat id-based
+      // (`m.id !== null`) porte implicitement un critère → non concerné.
+      //
+      // DB-F2 : on compte les filtres EFFECTIFS, pas la seule présence d'entrées.
+      // `.or([])` pousse un OrGroup vide (`{filters:[]}`) et `.filter('','','')`
+      // pousse un filtre à colonne vide — aucun des deux n'émet de critère
+      // PostgREST. Les ignorer ferme le contournement du garde-fou.
+      const hasEffectiveFilter =
+        this._filters.some((f) => f.column !== '') ||
+        this._orGroups.some((g) => g.filters.length > 0)
+      if (
+        (m.type === 'update' || m.type === 'delete') &&
+        m.id === null &&
+        !hasEffectiveFilter
+      ) {
+        return {
+          data: null,
+          error: new AuraError(0, {
+            error: {
+              code: 'unfiltered_mutation',
+              message:
+                'update()/delete() sans filtre refusé (protection anti-wipe) — ajoutez un filtre .eq()/... ou utilisez une mutation id-based',
+            },
+          }),
+        }
+      }
+
+      // En-tête Prefer : `return=representation` si `.select()` (indispensable
+      // pour récupérer les lignes sur un DELETE ; inoffensif sur PATCH/POST) ;
+      // `count=<mode>` si `.count()` (parité PostgREST — sur mutation le comptage
+      // passe par Prefer, pas par le query param).
+      const prefer: string[] = []
+      if (this._selectInvoked) prefer.push('return=representation')
+      if (this._count) prefer.push(`count=${this._count}`)
+      // Fusion Prefer (mutation) + Accept object+json (single) — `.eq().update().select().single()`.
+      const merged: Record<string, string> = { ...acceptSingle }
+      if (prefer.length > 0) merged.Prefer = prefer.join(', ')
+      const headers = Object.keys(merged).length > 0 ? merged : undefined
+
+      // Query string commune (select + filtres) via le builder partagé.
+      const qs = this.buildQueryString()
+      const sep = qs ? '?' : ''
+
+      switch (m.type) {
+        case 'insert': {
+          res = await fetchWithAuth<Result>(
+            `${this._client.baseUrl}${this._basePath}${sep}${qs}`,
+            { method: 'POST', body: m.body, headers },
+            this._client,
+          )
+          break
+        }
+        case 'update': {
+          // Compat : route id-based `/{basePath}/{id}` (rétro-compat exacte) ;
+          // sinon route Table filtrée `/{basePath}?filtres[&select]`.
+          const path = m.id !== null ? `${this._basePath}/${m.id}` : this._basePath
+          res = await fetchWithAuth<Result>(
+            `${this._client.baseUrl}${path}${sep}${qs}`,
+            { method: 'PATCH', body: m.body, headers },
+            this._client,
+          )
+          break
+        }
+        case 'delete': {
+          const path = m.id !== null ? `${this._basePath}/${m.id}` : this._basePath
+          res = await fetchWithAuth<Result>(
+            `${this._client.baseUrl}${path}${sep}${qs}`,
+            { method: 'DELETE', headers },
+            this._client,
+          )
+          break
+        }
+        case 'upsert': {
+          // `on_conflict` fusionné avec les éventuels filtres/select.
+          const params = new URLSearchParams(qs)
+          params.set('on_conflict', m.onConflict)
+          res = await fetchWithAuth<Result>(
+            `${this._client.baseUrl}${this._basePath}?${params.toString()}`,
+            { method: 'POST', body: m.body, headers },
+            this._client,
+          )
+          break
+        }
+      }
+    } else {
+      // SELECT
+      const qs = this.buildQueryString()
+      const sep = qs ? '?' : ''
+      res = await fetchWithAuth<Result>(
+        `${this._client.baseUrl}${this._basePath}${sep}${qs}`,
+        { method: 'GET', headers: acceptSingle },
+        this._client,
+      )
+    }
+
+    // DB-F3 : parité postgrest-js — `insert()`/`upsert()` sans `.single()` promettent
+    // TOUJOURS un tableau (`Row[]`). Le gateway déballe le 201 mono-ligne en objet
+    // (postgrest_proxy : branche `is_created`, arr.len()==1 → unwrap). On re-emballe
+    // en tableau à 1 élément pour honorer le type de retour. N'affecte ni les inserts
+    // multi-lignes (déjà un tableau), ni `.single()` (bloc ci-dessous), ni un 204
+    // sans représentation (`res.data === null`).
+    if (
+      !this._single &&
+      (this._mutation?.type === 'insert' || this._mutation?.type === 'upsert') &&
+      res.data !== null &&
+      typeof res.data === 'object' &&
+      !Array.isArray(res.data)
+    ) {
+      res = { ...res, data: [res.data] as unknown as Result }
+    }
+
+    // Single / maybeSingle : cardinalité stricte (parité PostgREST/Supabase).
+    //
+    // Chemin nominal (backend honore Accept object+json) :
+    //   - 1 ligne  → `res.data` est déjà l'objet (pas un tableau) → renvoyé tel quel.
+    //   - 0 / >1   → 406 (gateway : code `NOT_SINGULAR`, détail PostgREST « N rows »).
+    //     • single       → erreur PGRST116 (exige exactement 1 ligne).
+    //     • maybeSingle  → 0 ligne = `{data:null,error:null}` ; >1 = erreur PGRST116.
+    // Chemin défensif : si le backend renvoie malgré tout un TABLEAU (en-tête ignoré,
+    //   mock de test…), on réduit avec la même sémantique.
+    if (this._single) {
+      if (res.error) {
+        // Cardinalité 0-ligne, selon la route empruntée par la mutation/lecture :
+        //  - 406 NOT_SINGULAR (route Table/filtrée) : discrimine 0 vs >1 via le
+        //    détail PostgREST (« N rows »).
+        //  - 404 RECORD_NOT_FOUND (DB-F1) : le gateway réécrit PGRST116 en 404 sur
+        //    la route id-based `/{table}/{id}` (postgrest_proxy `is_single_object`).
+        //    C'est TOUJOURS un cas 0-ligne (l'id n'existe pas) — jamais « >1 ».
+        // `zero === null` → autre erreur (401/500…), propagée telle quelle.
+        const zero =
+          res.error.status === 406
+            ? mentionsZeroRows(res.error)
+            : res.error.status === 404 && res.error.code === 'RECORD_NOT_FOUND'
+              ? true
+              : null
+        if (zero !== null) {
+          res =
+            this._maybeSingle && zero
+              ? { ...res, data: null, error: null }
+              : { ...res, data: null, error: pgrst116(zero) }
+        }
+      } else if (Array.isArray(res.data)) {
+        const rows = res.data as unknown[]
+        if (this._maybeSingle) {
+          res =
+            rows.length > 1
+              ? { ...res, data: null, error: pgrst116(false) }
+              : { ...res, data: (rows[0] as Result | undefined) ?? null }
+        } else if (rows.length === 1) {
+          res = { ...res, data: rows[0] as Result }
+        } else {
+          res = { ...res, data: null, error: pgrst116(rows.length === 0) }
+        }
+      }
+      // Sinon : `res.data` est déjà l'objet unique → renvoyé tel quel.
+    }
+
+    // Throw mode
+    if (this._throwOnError && res.error) {
+      const err = new Error(res.error.message)
+      ;(err as unknown as Record<string, unknown>).code = res.error.code
+      ;(err as unknown as Record<string, unknown>).details = res.error.details
+      throw err
+    }
+
+    return res
+  }
+}
+
+/**
+ * Sélection de colonnes, tri, pagination et modificateurs de cardinalité
+ * (`single`/`maybeSingle`/`count`).
+ */
+export class AuraTransformBuilder<
+  Schema extends GenericSchema = GenericSchema,
+  Row extends Record<string, unknown> = Record<string, unknown>,
+  RelationName = unknown,
+  Relationships = unknown,
+  Result = Record<string, unknown>,
+  ClientOptions extends ClientServerOptions = AuraClientOptionsT,
+  ThrowOnError extends boolean = false,
+> extends AuraPostgrestBuilder<ClientOptions, Result, ThrowOnError> {
+  // -- Column selection & resource embedding -----------------------------------
+
+  /**
+   * Select columns and optionally embed related resources (PostgREST parity).
+   *
+   * @example
+   * // Simple columns
+   * db.from('users').select('id, name, email')
+   *
+   * // All columns (default)
+   * db.from('users').select('*')
+   *
+   * // Embed related table (many-to-one)
+   * db.from('orders').select('*, customer:customers(name, email)')
+   *
+   * // Embed related table (one-to-many)
+   * db.from('directors').select('last_name, films(title, year)')
+   *
+   * // FK disambiguation
+   * db.from('orders').select('*, billing:addresses!billing_address_id(name)')
+   *
+   * // Nested embedding
+   * db.from('actors').select('first_name, roles(character, films(title))')
+   */
+  select<
+    Query extends string = '*',
+    NewResultOne = GetResult<Schema, Row, RelationName, Relationships, Query, ClientOptions>,
+  >(
+    columns?: Query,
+  ): AuraFilterBuilder<
+    Schema,
+    Row,
+    RelationName,
+    Relationships,
+    NewResultOne[],
+    ClientOptions,
+    ThrowOnError
+  > {
+    // Runtime inchangé : accepte aussi un tableau de colonnes (parité historique),
+    // le typage n'expose que la forme string literal pour l'inférence PostgREST.
+    this._selectInvoked = true
+    const cols = columns as unknown as string | string[] | undefined
+    if (cols === undefined || cols === '*') {
+      this._selectColumns = null
+      this._rawSelect = false
+    } else if (typeof cols === 'string') {
+      // If string contains parentheses → embed syntax, pass raw to backend
+      // Otherwise → simple comma-separated column list
+      if (cols.includes('(')) {
+        this._selectColumns = [cols]
+        this._rawSelect = true
+      } else {
+        this._selectColumns = cols.split(',').map((c) => c.trim())
+        this._rawSelect = false
+      }
+    } else {
+      this._selectColumns = cols
+      this._rawSelect = false
+    }
+    return this as unknown as AuraFilterBuilder<
+      Schema,
+      Row,
+      RelationName,
+      Relationships,
+      NewResultOne[],
+      ClientOptions,
+      ThrowOnError
+    >
+  }
+
+  // -- Sort / pagination ------------------------------------------------------
+
+  order(column: string, direction: 'asc' | 'desc' = 'asc'): this {
+    this._sortColumn = column
+    this._sortDirection = direction
+    return this
+  }
+
+  limit(n: number): this {
+    this._limit = n
+    return this
+  }
+
+  offset(n: number): this {
+    this._offset = n
+    return this
+  }
+
+  /**
+   * Pagination keyset : passer le `next_cursor` opaque de la page précédente (préférable à
+   * `offset` sur les grandes tables : stable, sans dup/skip). Renvoyer tel quel `meta.next_cursor` ;
+   * ne pas le construire/parser (format opaque).
+   */
+  cursor(cursor: string): this {
+    this._cursor = cursor
+    return this
+  }
+
+  count(mode: CountMode = 'exact'): this {
+    this._count = mode
+    return this
+  }
+
+  // -- Modifiers --------------------------------------------------------------
+
+  single<ResultOne = Result extends (infer U)[] ? U : Result>(): AuraPostgrestBuilder<
+    ClientOptions,
+    ResultOne,
+    ThrowOnError
+  > {
+    this._single = true
+    // Parité postgrest-js : `_execute` envoie `Accept: application/vnd.pgrst.object+json`.
+    // PostgREST renvoie alors l'objet unique (200) ou 406 PGRST116 (0/>1 lignes). On
+    // n'ajoute PLUS `limit=2` : PostgREST rejette `limit` sans `order` sur une mutation
+    // filtrée (`.eq().update().select().single()` cassait). L'en-tête traverse le gateway
+    // (route Table) jusqu'à PostgREST — cf. postgrest_proxy `req.into_parts()`.
+    return this as unknown as AuraPostgrestBuilder<ClientOptions, ResultOne, ThrowOnError>
+  }
+
+  maybeSingle<ResultOne = Result extends (infer U)[] ? U : Result>(): AuraPostgrestBuilder<
+    ClientOptions,
+    ResultOne | null,
+    ThrowOnError
+  > {
+    this._single = true
+    this._maybeSingle = true
+    // Même en-tête `Accept: object+json`. Différence : sur 406 « 0 rows » → `{data:null,error:null}`
+    // (0 ligne n'est pas une erreur pour maybeSingle) ; sur >1 ligne → erreur PGRST116.
+    return this as unknown as AuraPostgrestBuilder<ClientOptions, ResultOne | null, ThrowOnError>
+  }
+}
+
+/**
+ * Tous les filtres PostgREST (`eq`, `neq`, ... `ilikeAnyOf`).
+ */
+export class AuraFilterBuilder<
+  Schema extends GenericSchema = GenericSchema,
+  Row extends Record<string, unknown> = Record<string, unknown>,
+  RelationName = unknown,
+  Relationships = unknown,
+  Result = Record<string, unknown>,
+  ClientOptions extends ClientServerOptions = AuraClientOptionsT,
+  ThrowOnError extends boolean = false,
+> extends AuraTransformBuilder<
+  Schema,
+  Row,
+  RelationName,
+  Relationships,
+  Result,
+  ClientOptions,
+  ThrowOnError
+> {
+  // -- Filter methods (each returns this for chaining) ------------------------
+  //
+  // Typées sur `Row` : `column` est contraint à `keyof Row & string` (autocomplete +
+  // erreur de compilation sur colonne inconnue) et `value`/`values` à `Row[C]` (erreur
+  // sur mauvais type). Runtime inchangé — seules les signatures changent.
+
+  eq<C extends keyof Row & string>(column: C, value: Row[C]): this {
+    this._filters.push({ column, op: 'eq', value })
+    return this
+  }
+
+  neq<C extends keyof Row & string>(column: C, value: Row[C]): this {
+    this._filters.push({ column, op: 'neq', value })
+    return this
+  }
+
+  gt<C extends keyof Row & string>(column: C, value: Row[C]): this {
+    this._filters.push({ column, op: 'gt', value })
+    return this
+  }
+
+  gte<C extends keyof Row & string>(column: C, value: Row[C]): this {
+    this._filters.push({ column, op: 'gte', value })
+    return this
+  }
+
+  lt<C extends keyof Row & string>(column: C, value: Row[C]): this {
+    this._filters.push({ column, op: 'lt', value })
+    return this
+  }
+
+  lte<C extends keyof Row & string>(column: C, value: Row[C]): this {
+    this._filters.push({ column, op: 'lte', value })
+    return this
+  }
+
+  like(column: keyof Row & string, pattern: string): this {
+    this._filters.push({ column, op: 'like', value: pattern })
+    return this
+  }
+
+  ilike(column: keyof Row & string, pattern: string): this {
+    this._filters.push({ column, op: 'ilike', value: pattern })
+    return this
+  }
+
+  /**
+   * IS NULL or IS NOT NULL filter.
+   * PostgREST accepts: is.null, is.true, is.false (no "not_null" — use neq for that).
+   * For IS NOT NULL, use `neq(column, null)` or `is(column, 'not.null')`.
+   */
+  is(column: keyof Row & string, value: 'null' | 'true' | 'false' | 'unknown' | 'not.null'): this {
+    if (value === 'not.null') {
+      // IS NOT NULL en PostgREST = `col=not.is.null`. (`neq.null` produit `col <> NULL`,
+      // toujours NULL/faux en SQL → renverrait 0 ligne.)
+      this._filters.push({ column, op: 'not.is', value: 'null' })
+    } else {
+      this._filters.push({ column, op: 'is', value })
+    }
+    return this
+  }
+
+  in<C extends keyof Row & string>(column: C, values: Row[C][]): this {
+    this._filters.push({ column, op: 'in', value: values })
+    return this
+  }
+
+  /**
+   * Add an OR group: `or=(col1.eq.val1,col2.gt.val2)`
+   */
+  or(filters: Array<{ column: string; op: string; value: unknown }>): this {
+    this._orGroups.push({
+      filters: filters.map((f) => ({ column: f.column, op: f.op, value: f.value })),
+    })
+    return this
+  }
+
+  // -- Filtres étendus (parité PostgREST) -------------------------------------
+
+  notIn<C extends keyof Row & string>(column: C, values: Row[C][]): this { this._filters.push({ column, op: 'not.in', value: values }); return this }
+  contains(column: keyof Row & string, value: unknown): this { this._filters.push({ column, op: 'cs', value }); return this }
+  containedBy(column: keyof Row & string, value: unknown): this { this._filters.push({ column, op: 'cd', value }); return this }
+  overlaps(column: keyof Row & string, value: unknown): this { this._filters.push({ column, op: 'ov', value }); return this }
+  rangeGt(column: keyof Row & string, range: string): this { this._filters.push({ column, op: 'sr', value: range }); return this }
+  rangeGte(column: keyof Row & string, range: string): this { this._filters.push({ column, op: 'nxl', value: range }); return this }
+  rangeLt(column: keyof Row & string, range: string): this { this._filters.push({ column, op: 'sl', value: range }); return this }
+  rangeLte(column: keyof Row & string, range: string): this { this._filters.push({ column, op: 'nxr', value: range }); return this }
+  rangeAdjacent(column: keyof Row & string, range: string): this { this._filters.push({ column, op: 'adj', value: range }); return this }
+  isDistinct(column: keyof Row & string, value: unknown): this { this._filters.push({ column, op: 'isdistinct', value }); return this }
+  // Échappatoires (parité postgrest-js) : colonne `string` permissive, pas de contrainte sur `Row`.
+  not(column: string, op: string, value: unknown): this { this._filters.push({ column, op: `not.${op}`, value }); return this }
+  filter(column: string, op: string, value: unknown): this { this._filters.push({ column, op, value }); return this }
+  match(query: Record<string, unknown>): this {
+    for (const [column, value] of Object.entries(query)) this._filters.push({ column, op: 'eq', value })
+    return this
+  }
+  textSearch(column: keyof Row & string, query: string, options?: { type?: 'plain' | 'phrase' | 'websearch'; config?: string }): this {
+    const t = options?.type
+    const token = t === 'plain' ? 'plfts' : t === 'phrase' ? 'phfts' : t === 'websearch' ? 'wfts' : 'fts'
+    const op = options?.config ? `${token}(${options.config})` : token
+    this._filters.push({ column, op, value: query })
+    return this
+  }
+  likeAllOf(column: keyof Row & string, patterns: string[]): this { this._filters.push({ column, op: 'like(all)', value: patterns }); return this }
+  likeAnyOf(column: keyof Row & string, patterns: string[]): this { this._filters.push({ column, op: 'like(any)', value: patterns }); return this }
+  ilikeAllOf(column: keyof Row & string, patterns: string[]): this { this._filters.push({ column, op: 'ilike(all)', value: patterns }); return this }
+  ilikeAnyOf(column: keyof Row & string, patterns: string[]): this { this._filters.push({ column, op: 'ilike(any)', value: patterns }); return this }
+}
+
+/**
+ * Chainable query builder that compiles to URL query parameters
+ * matching the backend's QueryOptions / FilterOp format.
+ *
+ * Point d'entrée concret retourné par `DatabaseService.from()` : ajoute les
+ * mutations (`insert`/`update`/`delete`/`upsert`) au-dessus de la chaîne
+ * Base → Transform → Filter.
+ */
+export class AuraQueryBuilder<
+  Schema extends GenericSchema = GenericSchema,
+  Relation extends GenericTable | GenericView = GenericTable,
+  RelationName = unknown,
+  ClientOptions extends ClientServerOptions = AuraClientOptionsT,
+> extends AuraFilterBuilder<
+  Schema,
+  Relation['Row'],
+  RelationName,
+  Relation['Relationships'],
+  Relation['Row'][],
+  ClientOptions,
+  false
+> {
+  // -- Mutations --------------------------------------------------------------
+  //
+  // Typées sur `Relation['Insert']`/`Relation['Update']` (parité postgrest-js) :
+  // un champ requis manquant côté insert/upsert, ou une colonne inconnue côté
+  // update, est une erreur de compilation. Runtime inchangé.
+  //
+  // Extraction par type conditionnel (plutôt qu'un accès indexé direct
+  // `Relation['Insert']`) : `Relation` est contraint à `GenericTable | GenericView`
+  // et `GenericNonUpdatableView` ne porte pas `Insert`/`Update`. `infer` distribue
+  // sur cette union et retombe sur `never` pour la branche non-updatable, ce qui
+  // évite l'erreur TS2536 tout en gardant le typage strict pour les tables.
+
+  insert(
+    body: Relation extends { Insert: infer I } ? I | I[] : never,
+  ): this {
+    this._mutation = { type: 'insert', body }
+    return this
+  }
+
+  // `update`/`delete`/`upsert` retournent un `AuraFilterBuilder` (au lieu de
+  // `this`) : le mode filtré chaîne `.eq(...)` AVANT et `.select()` APRÈS la
+  // mutation (parité PostgREST). Deux formes pour `update` :
+  //   - COMPAT `update(id: string, body)` → route id-based `/{table}/{id}` ;
+  //   - FILTRÉ `update(body)` → route Table `/{table}?filtres`, exige un filtre
+  //     (garde-fou anti-wipe dans `_execute`).
+  update(
+    id: string,
+    body: Relation extends { Update: infer U } ? U : never,
+  ): AuraFilterBuilder<
+    Schema,
+    Relation['Row'],
+    RelationName,
+    Relation['Relationships'],
+    Relation['Row'][],
+    ClientOptions,
+    false
+  >
+  update(
+    body: Relation extends { Update: infer U } ? U : never,
+  ): AuraFilterBuilder<
+    Schema,
+    Relation['Row'],
+    RelationName,
+    Relation['Relationships'],
+    Relation['Row'][],
+    ClientOptions,
+    false
+  >
+  update(
+    idOrBody: string | (Relation extends { Update: infer U } ? U : never),
+    body?: Relation extends { Update: infer U } ? U : never,
+  ): AuraFilterBuilder<
+    Schema,
+    Relation['Row'],
+    RelationName,
+    Relation['Relationships'],
+    Relation['Row'][],
+    ClientOptions,
+    false
+  > {
+    if (typeof idOrBody === 'string') {
+      this._mutation = { type: 'update', id: idOrBody, body }
+    } else {
+      this._mutation = { type: 'update', id: null, body: idOrBody }
+    }
+    return this as unknown as AuraFilterBuilder<
+      Schema,
+      Relation['Row'],
+      RelationName,
+      Relation['Relationships'],
+      Relation['Row'][],
+      ClientOptions,
+      false
+    >
+  }
+
+  // COMPAT `delete(id)` → route id-based ; FILTRÉ `delete()` → route Table
+  // (exige un filtre, garde-fou anti-wipe).
+  delete(id?: string): AuraFilterBuilder<
+    Schema,
+    Relation['Row'],
+    RelationName,
+    Relation['Relationships'],
+    Relation['Row'][],
+    ClientOptions,
+    false
+  > {
+    this._mutation = { type: 'delete', id: typeof id === 'string' ? id : null }
+    return this as unknown as AuraFilterBuilder<
+      Schema,
+      Relation['Row'],
+      RelationName,
+      Relation['Relationships'],
+      Relation['Row'][],
+      ClientOptions,
+      false
+    >
+  }
+
+  upsert(
+    body: Relation extends { Insert: infer I } ? I | I[] : never,
+    options?: { onConflict?: string },
+  ): AuraFilterBuilder<
+    Schema,
+    Relation['Row'],
+    RelationName,
+    Relation['Relationships'],
+    Relation['Row'][],
+    ClientOptions,
+    false
+  > {
+    this._mutation = { type: 'upsert', body, onConflict: options?.onConflict ?? 'id' }
+    return this as unknown as AuraFilterBuilder<
+      Schema,
+      Relation['Row'],
+      RelationName,
+      Relation['Relationships'],
+      Relation['Row'][],
+      ClientOptions,
+      false
+    >
+  }
+}
+
+// Alias rétro-compatible : le nom `QueryBuilder` reste l'export public utilisé
+// par la façade et les tests existants.
+export { AuraQueryBuilder as QueryBuilder }