@linabase/js 0.3.0 → 0.4.0

package/dist/index.cjs

@@ -52,16 +52,16 @@ var DatabaseClient = class {
   // ─── Query Methods ──────────────────────────────────────
   /** Select columns. Supports nested joins: "*, comments(*)" and aliases: "full_name:name" */
   select(columns, options) {
-    this.method = "GET";
-    if (columns) this.params.set("select", columns);
+    this.method = options?.head ? "HEAD" : "GET";
+    if (columns && columns !== "*") this.params.set("select", columns);
     if (options?.count) this.preferHeaders.push(`count=${options.count}`);
-    if (options?.head) this.method = "GET";
     return this;
   }
-  insert(data) {
+  insert(data, options) {
     this.method = "POST";
     this.body = data;
     this.preferHeaders.push("return=representation");
+    if (options?.defaultToNull === false) this.preferHeaders.push("missing=default");
     return this;
   }
   /** Upsert: insert or update on conflict. Uses merge-duplicates by default. */
@@ -75,6 +75,7 @@ var DatabaseClient = class {
     if (options?.onConflict) {
       this.params.set("on_conflict", options.onConflict);
     }
+    if (options?.defaultToNull === false) this.preferHeaders.push("missing=default");
     return this;
   }
   update(data) {
@@ -83,8 +84,28 @@ var DatabaseClient = class {
     this.preferHeaders.push("return=representation");
     return this;
   }
-  delete() {
+  delete(options) {
     this.method = "DELETE";
+    if (options?.count) this.preferHeaders.push(`count=${options.count}`);
+    return this;
+  }
+  /** Specify return=minimal to skip returning data on mutations (better performance). */
+  returning(mode = "representation") {
+    this.preferHeaders = this.preferHeaders.filter((h) => !h.startsWith("return="));
+    this.preferHeaders.push(`return=${mode}`);
+    return this;
+  }
+  /** Get the query execution plan (EXPLAIN). */
+  explain(options) {
+    const parts = ["plan"];
+    if (options?.analyze) parts.push("analyze");
+    if (options?.verbose) parts.push("verbose");
+    if (options?.settings) parts.push("settings");
+    if (options?.buffers) parts.push("buffers");
+    if (options?.wal) parts.push("wal");
+    if (options?.format) parts.push(`format:${options.format}`);
+    this.preferHeaders = this.preferHeaders.filter((h) => !h.startsWith("plan"));
+    this.preferHeaders.push(parts.join("|"));
     return this;
   }
   // ─── Comparison Filters ─────────────────────────────────
@@ -168,6 +189,32 @@ var DatabaseClient = class {
     this.params.set(column, `isdistinct.${value}`);
     return this;
   }
+  // ─── Range Type Filters ──────────────────────────────────
+  /** Strictly left of: [a,b] << [c,d] */
+  rangeLt(column, range) {
+    this.params.set(column, `sl.${range}`);
+    return this;
+  }
+  /** Strictly right of: [a,b] >> [c,d] */
+  rangeGt(column, range) {
+    this.params.set(column, `sr.${range}`);
+    return this;
+  }
+  /** Does not extend to the left of */
+  rangeGte(column, range) {
+    this.params.set(column, `nxl.${range}`);
+    return this;
+  }
+  /** Does not extend to the right of */
+  rangeLte(column, range) {
+    this.params.set(column, `nxr.${range}`);
+    return this;
+  }
+  /** Range is adjacent to */
+  rangeAdjacent(column, range) {
+    this.params.set(column, `adj.${range}`);
+    return this;
+  }
   // ─── Negation ───────────────────────────────────────────
   /** Negate a filter: not.eq, not.in, not.is, etc. */
   not(column, operator, value) {
@@ -176,29 +223,53 @@ var DatabaseClient = class {
   }
   // ─── Logical ────────────────────────────────────────────
   /** OR filter: or("age.gt.20,name.eq.John") */
-  or(filters) {
-    this.params.set("or", `(${filters})`);
+  or(filters, options) {
+    const key = options?.foreignTable ? `${options.foreignTable}.or` : "or";
+    this.params.set(key, `(${filters})`);
+    return this;
+  }
+  /** AND filter: and("age.gt.20,name.eq.John") */
+  and(filters, options) {
+    const key = options?.foreignTable ? `${options.foreignTable}.and` : "and";
+    this.params.set(key, `(${filters})`);
+    return this;
+  }
+  /** Generic filter: filter("column", "operator", "value") */
+  filter(column, operator, value) {
+    this.params.set(column, `${operator}.${value}`);
     return this;
   }
   // ─── Full-Text Search ───────────────────────────────────
-  /** to_tsquery */
+  /** Full-text search (to_tsquery, plainto_tsquery, phraseto_tsquery, or websearch_to_tsquery) */
   textSearch(column, query, options) {
     const op = options?.type === "plain" ? "plfts" : options?.type === "phrase" ? "phfts" : options?.type === "websearch" ? "wfts" : "fts";
-    this.params.set(column, `${op}.${query}`);
+    const config = options?.config ? `(${options.config})` : "";
+    this.params.set(column, `${op}${config}.${query}`);
     return this;
   }
   // ─── Ordering & Pagination ──────────────────────────────
   order(column, options) {
     const dir = options?.ascending === false ? "desc" : "asc";
     const nulls = options?.nullsFirst === true ? ".nullsfirst" : options?.nullsFirst === false ? ".nullslast" : "";
-    const existing = this.params.get("order");
+    const key = options?.foreignTable ? `${options.foreignTable}.order` : "order";
+    const existing = this.params.get(key);
     if (existing) {
-      this.params.set("order", `${existing},${column}.${dir}${nulls}`);
+      this.params.set(key, `${existing},${column}.${dir}${nulls}`);
     } else {
-      this.params.set("order", `${column}.${dir}${nulls}`);
+      this.params.set(key, `${column}.${dir}${nulls}`);
     }
     return this;
   }
+  /** Limit results on a foreign table */
+  limitForeignTable(count, foreignTable) {
+    this.params.set(`${foreignTable}.limit`, String(count));
+    return this;
+  }
+  /** Offset results on a foreign table */
+  offsetForeignTable(count, foreignTable) {
+    this.params.set(`${foreignTable}.offset`, String(count));
+    return this;
+  }
   limit(count) {
     this.params.set("limit", String(count));
     return this;
@@ -269,6 +340,7 @@ var DatabaseClient = class {
   async execute() {
     const qs = this.params.toString();
     const path = `/rest/v1/${this.table}${qs ? `?${qs}` : ""}`;
+    const isHead = this.method === "HEAD";
     const isSingle = this._single;
     const isMaybeSingle = this._maybeSingle;
     const shouldThrow = this._throwOnError;
@@ -301,8 +373,11 @@ var DatabaseClient = class {
         body: this.body ? JSON.stringify(this.body) : void 0,
         signal: abortSignal
       });
-      const countHeader = res.headers.get("X-Total-Count");
+      const countHeader = res.headers.get("X-Total-Count") || res.headers.get("content-range")?.split("/")[1];
       const totalCount = countHeader ? parseInt(countHeader) : null;
+      if (isHead) {
+        return { data: null, error: res.ok ? null : { message: res.statusText }, count: totalCount };
+      }
       if (isCsv) {
         if (!res.ok) {
           const text = await res.text();

package/dist/index.d.cts

@@ -39,14 +39,30 @@ declare class DatabaseClient {
         count?: "exact" | "estimated" | "planned";
         head?: boolean;
     }): this;
-    insert(data: Record<string, any> | Record<string, any>[]): this;
+    insert(data: Record<string, any> | Record<string, any>[], options?: {
+        defaultToNull?: boolean;
+    }): this;
     /** Upsert: insert or update on conflict. Uses merge-duplicates by default. */
     upsert(data: Record<string, any> | Record<string, any>[], options?: {
         ignoreDuplicates?: boolean;
         onConflict?: string;
+        defaultToNull?: boolean;
     }): this;
     update(data: Record<string, any>): this;
-    delete(): this;
+    delete(options?: {
+        count?: "exact" | "estimated" | "planned";
+    }): this;
+    /** Specify return=minimal to skip returning data on mutations (better performance). */
+    returning(mode?: "minimal" | "representation"): this;
+    /** Get the query execution plan (EXPLAIN). */
+    explain(options?: {
+        analyze?: boolean;
+        verbose?: boolean;
+        settings?: boolean;
+        buffers?: boolean;
+        wal?: boolean;
+        format?: "json" | "text";
+    }): this;
     eq(column: string, value: any): this;
     neq(column: string, value: any): this;
     gt(column: string, value: any): this;
@@ -69,18 +85,42 @@ declare class DatabaseClient {
     is(column: string, value: "null" | "true" | "false" | null | boolean): this;
     /** IS DISTINCT FROM */
     isDistinct(column: string, value: any): this;
+    /** Strictly left of: [a,b] << [c,d] */
+    rangeLt(column: string, range: string): this;
+    /** Strictly right of: [a,b] >> [c,d] */
+    rangeGt(column: string, range: string): this;
+    /** Does not extend to the left of */
+    rangeGte(column: string, range: string): this;
+    /** Does not extend to the right of */
+    rangeLte(column: string, range: string): this;
+    /** Range is adjacent to */
+    rangeAdjacent(column: string, range: string): this;
     /** Negate a filter: not.eq, not.in, not.is, etc. */
     not(column: string, operator: string, value: any): this;
     /** OR filter: or("age.gt.20,name.eq.John") */
-    or(filters: string): this;
-    /** to_tsquery */
+    or(filters: string, options?: {
+        foreignTable?: string;
+    }): this;
+    /** AND filter: and("age.gt.20,name.eq.John") */
+    and(filters: string, options?: {
+        foreignTable?: string;
+    }): this;
+    /** Generic filter: filter("column", "operator", "value") */
+    filter(column: string, operator: string, value: any): this;
+    /** Full-text search (to_tsquery, plainto_tsquery, phraseto_tsquery, or websearch_to_tsquery) */
     textSearch(column: string, query: string, options?: {
         type?: "plain" | "phrase" | "websearch";
+        config?: string;
     }): this;
     order(column: string, options?: {
         ascending?: boolean;
         nullsFirst?: boolean;
+        foreignTable?: string;
     }): this;
+    /** Limit results on a foreign table */
+    limitForeignTable(count: number, foreignTable: string): this;
+    /** Offset results on a foreign table */
+    offsetForeignTable(count: number, foreignTable: string): this;
     limit(count: number): this;
     offset(count: number): this;
     /** Request exact, estimated, or planned count via Prefer header */

package/dist/index.d.ts

@@ -39,14 +39,30 @@ declare class DatabaseClient {
         count?: "exact" | "estimated" | "planned";
         head?: boolean;
     }): this;
-    insert(data: Record<string, any> | Record<string, any>[]): this;
+    insert(data: Record<string, any> | Record<string, any>[], options?: {
+        defaultToNull?: boolean;
+    }): this;
     /** Upsert: insert or update on conflict. Uses merge-duplicates by default. */
     upsert(data: Record<string, any> | Record<string, any>[], options?: {
         ignoreDuplicates?: boolean;
         onConflict?: string;
+        defaultToNull?: boolean;
     }): this;
     update(data: Record<string, any>): this;
-    delete(): this;
+    delete(options?: {
+        count?: "exact" | "estimated" | "planned";
+    }): this;
+    /** Specify return=minimal to skip returning data on mutations (better performance). */
+    returning(mode?: "minimal" | "representation"): this;
+    /** Get the query execution plan (EXPLAIN). */
+    explain(options?: {
+        analyze?: boolean;
+        verbose?: boolean;
+        settings?: boolean;
+        buffers?: boolean;
+        wal?: boolean;
+        format?: "json" | "text";
+    }): this;
     eq(column: string, value: any): this;
     neq(column: string, value: any): this;
     gt(column: string, value: any): this;
@@ -69,18 +85,42 @@ declare class DatabaseClient {
     is(column: string, value: "null" | "true" | "false" | null | boolean): this;
     /** IS DISTINCT FROM */
     isDistinct(column: string, value: any): this;
+    /** Strictly left of: [a,b] << [c,d] */
+    rangeLt(column: string, range: string): this;
+    /** Strictly right of: [a,b] >> [c,d] */
+    rangeGt(column: string, range: string): this;
+    /** Does not extend to the left of */
+    rangeGte(column: string, range: string): this;
+    /** Does not extend to the right of */
+    rangeLte(column: string, range: string): this;
+    /** Range is adjacent to */
+    rangeAdjacent(column: string, range: string): this;
     /** Negate a filter: not.eq, not.in, not.is, etc. */
     not(column: string, operator: string, value: any): this;
     /** OR filter: or("age.gt.20,name.eq.John") */
-    or(filters: string): this;
-    /** to_tsquery */
+    or(filters: string, options?: {
+        foreignTable?: string;
+    }): this;
+    /** AND filter: and("age.gt.20,name.eq.John") */
+    and(filters: string, options?: {
+        foreignTable?: string;
+    }): this;
+    /** Generic filter: filter("column", "operator", "value") */
+    filter(column: string, operator: string, value: any): this;
+    /** Full-text search (to_tsquery, plainto_tsquery, phraseto_tsquery, or websearch_to_tsquery) */
     textSearch(column: string, query: string, options?: {
         type?: "plain" | "phrase" | "websearch";
+        config?: string;
     }): this;
     order(column: string, options?: {
         ascending?: boolean;
         nullsFirst?: boolean;
+        foreignTable?: string;
     }): this;
+    /** Limit results on a foreign table */
+    limitForeignTable(count: number, foreignTable: string): this;
+    /** Offset results on a foreign table */
+    offsetForeignTable(count: number, foreignTable: string): this;
     limit(count: number): this;
     offset(count: number): this;
     /** Request exact, estimated, or planned count via Prefer header */

package/dist/index.js

@@ -20,16 +20,16 @@ var DatabaseClient = class {
   // ─── Query Methods ──────────────────────────────────────
   /** Select columns. Supports nested joins: "*, comments(*)" and aliases: "full_name:name" */
   select(columns, options) {
-    this.method = "GET";
-    if (columns) this.params.set("select", columns);
+    this.method = options?.head ? "HEAD" : "GET";
+    if (columns && columns !== "*") this.params.set("select", columns);
     if (options?.count) this.preferHeaders.push(`count=${options.count}`);
-    if (options?.head) this.method = "GET";
     return this;
   }
-  insert(data) {
+  insert(data, options) {
     this.method = "POST";
     this.body = data;
     this.preferHeaders.push("return=representation");
+    if (options?.defaultToNull === false) this.preferHeaders.push("missing=default");
     return this;
   }
   /** Upsert: insert or update on conflict. Uses merge-duplicates by default. */
@@ -43,6 +43,7 @@ var DatabaseClient = class {
     if (options?.onConflict) {
       this.params.set("on_conflict", options.onConflict);
     }
+    if (options?.defaultToNull === false) this.preferHeaders.push("missing=default");
     return this;
   }
   update(data) {
@@ -51,8 +52,28 @@ var DatabaseClient = class {
     this.preferHeaders.push("return=representation");
     return this;
   }
-  delete() {
+  delete(options) {
     this.method = "DELETE";
+    if (options?.count) this.preferHeaders.push(`count=${options.count}`);
+    return this;
+  }
+  /** Specify return=minimal to skip returning data on mutations (better performance). */
+  returning(mode = "representation") {
+    this.preferHeaders = this.preferHeaders.filter((h) => !h.startsWith("return="));
+    this.preferHeaders.push(`return=${mode}`);
+    return this;
+  }
+  /** Get the query execution plan (EXPLAIN). */
+  explain(options) {
+    const parts = ["plan"];
+    if (options?.analyze) parts.push("analyze");
+    if (options?.verbose) parts.push("verbose");
+    if (options?.settings) parts.push("settings");
+    if (options?.buffers) parts.push("buffers");
+    if (options?.wal) parts.push("wal");
+    if (options?.format) parts.push(`format:${options.format}`);
+    this.preferHeaders = this.preferHeaders.filter((h) => !h.startsWith("plan"));
+    this.preferHeaders.push(parts.join("|"));
     return this;
   }
   // ─── Comparison Filters ─────────────────────────────────
@@ -136,6 +157,32 @@ var DatabaseClient = class {
     this.params.set(column, `isdistinct.${value}`);
     return this;
   }
+  // ─── Range Type Filters ──────────────────────────────────
+  /** Strictly left of: [a,b] << [c,d] */
+  rangeLt(column, range) {
+    this.params.set(column, `sl.${range}`);
+    return this;
+  }
+  /** Strictly right of: [a,b] >> [c,d] */
+  rangeGt(column, range) {
+    this.params.set(column, `sr.${range}`);
+    return this;
+  }
+  /** Does not extend to the left of */
+  rangeGte(column, range) {
+    this.params.set(column, `nxl.${range}`);
+    return this;
+  }
+  /** Does not extend to the right of */
+  rangeLte(column, range) {
+    this.params.set(column, `nxr.${range}`);
+    return this;
+  }
+  /** Range is adjacent to */
+  rangeAdjacent(column, range) {
+    this.params.set(column, `adj.${range}`);
+    return this;
+  }
   // ─── Negation ───────────────────────────────────────────
   /** Negate a filter: not.eq, not.in, not.is, etc. */
   not(column, operator, value) {
@@ -144,29 +191,53 @@ var DatabaseClient = class {
   }
   // ─── Logical ────────────────────────────────────────────
   /** OR filter: or("age.gt.20,name.eq.John") */
-  or(filters) {
-    this.params.set("or", `(${filters})`);
+  or(filters, options) {
+    const key = options?.foreignTable ? `${options.foreignTable}.or` : "or";
+    this.params.set(key, `(${filters})`);
+    return this;
+  }
+  /** AND filter: and("age.gt.20,name.eq.John") */
+  and(filters, options) {
+    const key = options?.foreignTable ? `${options.foreignTable}.and` : "and";
+    this.params.set(key, `(${filters})`);
+    return this;
+  }
+  /** Generic filter: filter("column", "operator", "value") */
+  filter(column, operator, value) {
+    this.params.set(column, `${operator}.${value}`);
     return this;
   }
   // ─── Full-Text Search ───────────────────────────────────
-  /** to_tsquery */
+  /** Full-text search (to_tsquery, plainto_tsquery, phraseto_tsquery, or websearch_to_tsquery) */
   textSearch(column, query, options) {
     const op = options?.type === "plain" ? "plfts" : options?.type === "phrase" ? "phfts" : options?.type === "websearch" ? "wfts" : "fts";
-    this.params.set(column, `${op}.${query}`);
+    const config = options?.config ? `(${options.config})` : "";
+    this.params.set(column, `${op}${config}.${query}`);
     return this;
   }
   // ─── Ordering & Pagination ──────────────────────────────
   order(column, options) {
     const dir = options?.ascending === false ? "desc" : "asc";
     const nulls = options?.nullsFirst === true ? ".nullsfirst" : options?.nullsFirst === false ? ".nullslast" : "";
-    const existing = this.params.get("order");
+    const key = options?.foreignTable ? `${options.foreignTable}.order` : "order";
+    const existing = this.params.get(key);
     if (existing) {
-      this.params.set("order", `${existing},${column}.${dir}${nulls}`);
+      this.params.set(key, `${existing},${column}.${dir}${nulls}`);
     } else {
-      this.params.set("order", `${column}.${dir}${nulls}`);
+      this.params.set(key, `${column}.${dir}${nulls}`);
     }
     return this;
   }
+  /** Limit results on a foreign table */
+  limitForeignTable(count, foreignTable) {
+    this.params.set(`${foreignTable}.limit`, String(count));
+    return this;
+  }
+  /** Offset results on a foreign table */
+  offsetForeignTable(count, foreignTable) {
+    this.params.set(`${foreignTable}.offset`, String(count));
+    return this;
+  }
   limit(count) {
     this.params.set("limit", String(count));
     return this;
@@ -237,6 +308,7 @@ var DatabaseClient = class {
   async execute() {
     const qs = this.params.toString();
     const path = `/rest/v1/${this.table}${qs ? `?${qs}` : ""}`;
+    const isHead = this.method === "HEAD";
     const isSingle = this._single;
     const isMaybeSingle = this._maybeSingle;
     const shouldThrow = this._throwOnError;
@@ -269,8 +341,11 @@ var DatabaseClient = class {
         body: this.body ? JSON.stringify(this.body) : void 0,
         signal: abortSignal
       });
-      const countHeader = res.headers.get("X-Total-Count");
+      const countHeader = res.headers.get("X-Total-Count") || res.headers.get("content-range")?.split("/")[1];
       const totalCount = countHeader ? parseInt(countHeader) : null;
+      if (isHead) {
+        return { data: null, error: res.ok ? null : { message: res.statusText }, count: totalCount };
+      }
       if (isCsv) {
         if (!res.ok) {
           const text = await res.text();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linabase/js",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "JavaScript/TypeScript client SDK for Linabase (database, storage, auth)",
   "license": "MIT",
   "type": "module",