@linabase/js 0.3.1 → 0.4.1

package/dist/index.cjs

@@ -57,10 +57,11 @@ var DatabaseClient = class {
     if (options?.count) this.preferHeaders.push(`count=${options.count}`);
     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. */
@@ -74,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) {
@@ -82,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 ─────────────────────────────────
@@ -167,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) {
@@ -175,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;
@@ -622,6 +694,8 @@ var BucketClient = class {
 var AuthClient = class {
   request;
   listeners = [];
+  /** Promise that resolves when session restore from storage is complete. */
+  _restorePromise = Promise.resolve();
   currentSession = null;
   /**
    * Callback that the parent LinabaseClient can set to update the Authorization
@@ -992,6 +1066,11 @@ var AuthClient = class {
   // ─── Auth State Listener ───────────────────────────────────
   onAuthStateChange(callback) {
     this.listeners.push(callback);
+    this._restorePromise.then(() => {
+      if (this.listeners.includes(callback)) {
+        callback("INITIAL_SESSION", this.currentSession);
+      }
+    });
     return {
       unsubscribe: () => {
         this.listeners = this.listeners.filter((l) => l !== callback);
@@ -1089,7 +1168,7 @@ function createClient(config) {
         sessionStorage.removeItem(sessionKey);
       }
     });
-    Promise.resolve(sessionStorage.getItem(sessionKey)).then((raw) => {
+    authClient._restorePromise = Promise.resolve(sessionStorage.getItem(sessionKey)).then((raw) => {
       if (raw) {
         try {
           authClient.setSession(JSON.parse(raw));

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 */
@@ -226,6 +266,8 @@ interface AuthUser {
 declare class AuthClient {
     private request;
     private listeners;
+    /** Promise that resolves when session restore from storage is complete. */
+    _restorePromise: Promise<void>;
     private currentSession;
     /**
      * Callback that the parent LinabaseClient can set to update the Authorization

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 */
@@ -226,6 +266,8 @@ interface AuthUser {
 declare class AuthClient {
     private request;
     private listeners;
+    /** Promise that resolves when session restore from storage is complete. */
+    _restorePromise: Promise<void>;
     private currentSession;
     /**
      * Callback that the parent LinabaseClient can set to update the Authorization

package/dist/index.js

@@ -25,10 +25,11 @@ var DatabaseClient = class {
     if (options?.count) this.preferHeaders.push(`count=${options.count}`);
     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. */
@@ -42,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) {
@@ -50,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 ─────────────────────────────────
@@ -135,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) {
@@ -143,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;
@@ -590,6 +662,8 @@ var BucketClient = class {
 var AuthClient = class {
   request;
   listeners = [];
+  /** Promise that resolves when session restore from storage is complete. */
+  _restorePromise = Promise.resolve();
   currentSession = null;
   /**
    * Callback that the parent LinabaseClient can set to update the Authorization
@@ -960,6 +1034,11 @@ var AuthClient = class {
   // ─── Auth State Listener ───────────────────────────────────
   onAuthStateChange(callback) {
     this.listeners.push(callback);
+    this._restorePromise.then(() => {
+      if (this.listeners.includes(callback)) {
+        callback("INITIAL_SESSION", this.currentSession);
+      }
+    });
     return {
       unsubscribe: () => {
         this.listeners = this.listeners.filter((l) => l !== callback);
@@ -1057,7 +1136,7 @@ function createClient(config) {
         sessionStorage.removeItem(sessionKey);
       }
     });
-    Promise.resolve(sessionStorage.getItem(sessionKey)).then((raw) => {
+    authClient._restorePromise = Promise.resolve(sessionStorage.getItem(sessionKey)).then((raw) => {
       if (raw) {
         try {
           authClient.setSession(JSON.parse(raw));

package/package.json

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