supastash 0.1.62 → 0.2.1

package/dist/shared/utils/fetchData/liteHelpers.js

@@ -0,0 +1,92 @@
+import { getTableSchema } from "../getTableSchema";
+import { logError, logWarn } from "../logs";
+import { ReusedHelpers } from "../reusedHelpers";
+export function parseJSONColumns(row) {
+    const parsedRow = { ...row };
+    const errors = [];
+    for (const key in parsedRow) {
+        const value = parsedRow[key];
+        if (typeof value === "string" &&
+            (value.startsWith("{") || value.startsWith("["))) {
+            try {
+                parsedRow[key] = JSON.parse(value);
+            }
+            catch (error) {
+                errors.push(`Failed to parse JSON in column ${key}: ${error}`);
+            }
+        }
+    }
+    if (errors.length > 0) {
+        logWarn(`[Supastash] JSON parsing errors: ${errors.join(", ")}`);
+    }
+    return parsedRow;
+}
+export function sanitizeTableName(table) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(table)) {
+        throw new Error(`Invalid table name: ${table}`);
+    }
+    return table;
+}
+export function sanitizeOrderBy(orderBy) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(orderBy)) {
+        throw new Error(`Invalid order by column: ${orderBy}`);
+    }
+    return orderBy;
+}
+function buildFilterKey(table, filters) {
+    return `${table}:${JSON.stringify(filters ?? [])}`;
+}
+const filterCache = new Map();
+export async function buildFilters(filters, table, noChecks = false) {
+    if (!filters || filters.length === 0)
+        return "";
+    const filterKey = buildFilterKey(table, filters);
+    let sqlFilter = filterCache.get(filterKey);
+    try {
+        let schemaColumns = [];
+        if (!noChecks) {
+            const schema = await getTableSchema(table);
+            schemaColumns = schema.map((col) => col.trim().toLowerCase());
+        }
+        const filterStringArray = [];
+        for (const filter of filters) {
+            if ("or" in filter) {
+                try {
+                    const filterSql = ReusedHelpers.buildFilterForSql(filter);
+                    if (filterSql) {
+                        filterStringArray.push(filterSql);
+                    }
+                }
+                catch (error) {
+                    logError(`[Supastash] Failed to build OR filter for table ${table}:`, error);
+                }
+                continue;
+            }
+            if (!filter?.column) {
+                logWarn(`[Supastash] Skipping filter with missing column`);
+                continue;
+            }
+            const columnLower = String(filter.column).trim().toLowerCase();
+            if (!noChecks && !schemaColumns.includes(columnLower)) {
+                logWarn(`[Supastash] Filter column ${String(filter.column)} does not exist in table ${table}`);
+                continue;
+            }
+            try {
+                const filterSql = ReusedHelpers.buildFilterForSql(filter);
+                if (filterSql) {
+                    filterStringArray.push(filterSql);
+                }
+            }
+            catch (error) {
+                logError(`[Supastash] Failed to build filter for column ${String(filter.column)}:`, error);
+            }
+        }
+        return filterStringArray.length > 0
+            ? ` AND ${filterStringArray.join(" AND ")}`
+            : "";
+    }
+    catch (error) {
+        logError(`[Supastash] Failed to build filters for table ${table}:`, error);
+        return "";
+    }
+}

package/dist/shared/utils/fetchData/realTimeCall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realTimeCall.d.ts","sourceRoot":"","sources":["../../../../src/shared/utils/fetchData/realTimeCall.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAQjE,QAAA,MAAM,eAAe,GACnB,OAAO,MAAM,EACb,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,IAAI,EAC5D,SAAS,eAAe,EACxB,aAAa,OAAO,EACpB,UAAU,OAAO,SAuElB,CAAC;AAEF,eAAe,eAAe,CAAC"}

package/dist/{utils → shared/utils}/fetchData/realTimeCall.js

@@ -2,12 +2,12 @@ import { useEffect, useMemo, useState } from "react";
 import { getSupastashConfig } from "../../core/config";
 import { supastashEventBus } from "../events/eventBus";
 import { logError } from "../logs";
+import { ReusedHelpers } from "../reusedHelpers";
 import { supabaseClientErr } from "../supabaseClientErr";
-import { buildFilterString } from "./buildFilter";
 const hasRegistered = new Map();
 const useRealtimeData = (table, queueHandler, options, initialized, realtime) => {
     const { lazy, shouldFetch } = options;
-    const filterString = useMemo(() => buildFilterString(options.filter), [options.filter]);
+    const filterString = useMemo(() => ReusedHelpers.buildFilterString(options.filter), [options.filter]);
     const subKey = useMemo(() => `${table}:${filterString ?? ""}`, [table, filterString]);
     const [version, setVersion] = useState(0);
     useEffect(() => {

package/dist/shared/utils/fetchData/realTimeManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realTimeManager.d.ts","sourceRoot":"","sources":["../../../../src/shared/utils/fetchData/realTimeManager.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,YAAY,EACZ,MAAM,EAGP,MAAM,gCAAgC,CAAC;AAIxC,cAAM,wBAAwB;IAE5B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAyC;IAEhE,OAAO,CAAC,UAAU,CAAgC;IAClD,OAAO,CAAC,aAAa,CAAsD;IAC3E,OAAO,CAAC,WAAW,CAAkB;IAErC,OAAO,CAAC,gBAAgB,CAIK;IAC7B,OAAO,CAAC,iBAAiB,CAAa;IACtC,OAAO,CAAC,oBAAoB,CAAa;IACzC,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,sBAAsB,CAA8C;IAC5E,OAAO,CAAC,uBAAuB,CAA8C;IAC7E,OAAO,CAAC,eAAe,CAA4C;IAEnE,OAAO;IAEP,MAAM,CAAC,WAAW,IAAI,wBAAwB;IAO9C,OAAO,CAAC,kBAAkB;YAQZ,gBAAgB;YAmBhB,mBAAmB;IAoCjC,OAAO,CAAC,qBAAqB;IAK7B,OAAO,CAAC,uBAAuB;IAK/B,OAAO,CAAC,iBAAiB;YAiBX,SAAS;YAYT,cAAc;YAcd,iBAAiB;IAgC/B,OAAO,CAAC,OAAO;IAcf,OAAO,CAAC,qBAAqB;IAU7B,OAAO,CAAC,kBAAkB;IAuB1B,OAAO,CAAC,mBAAmB;IAepB,SAAS,CACd,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,YAAY,EACrB,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI;IA4BA,WAAW,CAChB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI;IAkBA,mBAAmB,IAAI,MAAM;IAI7B,cAAc,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAO9D,sBAAsB,IAAI,MAAM;IAIhC,cAAc,IAAI,IAAI;CAI9B;AAED,eAAO,MAAM,eAAe,0BAAyC,CAAC;AAEtE,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,YAAY,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,IAAI,EACpD,MAAM,GAAE,MAA8C,GACrD,IAAI,CAEN;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,YAAY,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,IAAI,EACpD,MAAM,EAAE,MAAM,GACb,IAAI,CAEN"}

package/dist/shared/utils/fetchData/registerSub.d.ts

@@ -0,0 +1,4 @@
+import { SupastashFilter } from "../../types/realtimeData.types";
+export declare function registerSub(table: string, filter?: SupastashFilter): boolean;
+export declare function unregisterSub(table: string, filter?: SupastashFilter): void;
+//# sourceMappingURL=registerSub.d.ts.map

package/dist/shared/utils/fetchData/registerSub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registerSub.d.ts","sourceRoot":"","sources":["../../../../src/shared/utils/fetchData/registerSub.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAKjE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,OAAO,CAQ5E;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,IAAI,CAQ3E"}

package/dist/{hooks/supastashData → shared/utils/fetchData}/registerSub.js

@@ -1,7 +1,7 @@
-import { buildFilterString } from "../../utils/fetchData/buildFilter";
+import { ReusedHelpers } from "../reusedHelpers";
 const subRegistry = {};
 export function registerSub(table, filter) {
-    const key = `${table}::${buildFilterString(filter) ?? ""}`;
+    const key = `${table}::${ReusedHelpers.buildFilterString(filter) ?? ""}`;
     if (subRegistry[key]) {
         subRegistry[key]++;
         return true;
@@ -10,7 +10,7 @@ export function registerSub(table, filter) {
     return false;
 }
 export function unregisterSub(table, filter) {
-    const key = `${table}::${buildFilterString(filter) ?? ""}`;
+    const key = `${table}::${ReusedHelpers.buildFilterString(filter) ?? ""}`;
     if (subRegistry[key]) {
         subRegistry[key]--;
         if (subRegistry[key] <= 0) {

package/dist/shared/utils/fetchData/setDataInBatches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setDataInBatches.d.ts","sourceRoot":"","sources":["../../../../src/shared/utils/fetchData/setDataInBatches.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,EAC7B,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,QAqBvE"}

package/dist/shared/utils/fetchData/snapShot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapShot.d.ts","sourceRoot":"","sources":["../../../../src/shared/utils/fetchData/snapShot.ts"],"names":[],"mappings":"AAKA,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAOnE;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,QAE9C;AAID,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,OAoBxC"}

package/dist/shared/utils/fetchData/validatePayload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validatePayload.d.ts","sourceRoot":"","sources":["../../../../src/shared/utils/fetchData/validatePayload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAE7D;;;GAGG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,WAAW,iBAgBzD;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,WAAW,EAAE,QAgB7D"}

package/dist/shared/utils/genUUID.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"genUUID.d.ts","sourceRoot":"","sources":["../../../src/shared/utils/genUUID.ts"],"names":[],"mappings":"AAAA,wBAAgB,cAAc,WAM7B"}

package/dist/shared/utils/getSafeValues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getSafeValues.d.ts","sourceRoot":"","sources":["../../../src/shared/utils/getSafeValues.ts"],"names":[],"mappings":"AA6FA,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CA2C7E"}

package/dist/shared/utils/getTableSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getTableSchema.d.ts","sourceRoot":"","sources":["../../../src/shared/utils/getTableSchema.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAkBrE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,EAAE,MAAM,QAM9C"}

package/dist/{utils → shared/utils}/logs.d.ts

@@ -1,3 +1,4 @@
+export declare const isDebugMode: () => boolean;
 /**
  * Logs a message to the console if debug mode is enabled
  * @param args - The arguments to log

package/dist/shared/utils/logs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logs.d.ts","sourceRoot":"","sources":["../../../src/shared/utils/logs.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,WAAW,eAEvB,CAAC;AAEF;;;GAGG;AACH,QAAA,MAAM,GAAG,GAAI,GAAG,MAAM,GAAG,EAAE,SAI1B,CAAC;AAEF,eAAe,GAAG,CAAC;AAEnB;;;GAGG;AACH,QAAA,MAAM,QAAQ,GAAI,GAAG,MAAM,GAAG,EAAE,SAG/B,CAAC;AAEF;;;GAGG;AACH,QAAA,MAAM,OAAO,GAAI,GAAG,MAAM,GAAG,EAAE,SAG9B,CAAC;AAEF,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC"}

package/dist/{utils → shared/utils}/logs.js

@@ -1,5 +1,10 @@
 import { getSupastashConfig } from "../core/config";
-const DEBUG_MODE = __DEV__; // Log only in dev mode
+const DEBUG_MODE = typeof __DEV__ !== "undefined"
+    ? __DEV__ // React Native
+    : process.env.NODE_ENV === "development";
+export const isDebugMode = () => {
+    return DEBUG_MODE;
+};
 /**
  * Logs a message to the console if debug mode is enabled
  * @param args - The arguments to log

package/dist/{utils → shared/utils}/query/builder/crud.d.ts

@@ -18,27 +18,27 @@ export default class SupastashCrudBuilder<T extends CrudMethods, U extends boole
      * @param data - The data to insert. Could be a single object or an array of objects.
      * @returns filter options.
      */
-    insert<Z = any>(data: R): SupastashFilterBuilder<"insert", false, R, Z>;
+    insert<Z = any>(data: R): Omit<SupastashFilterBuilder<"insert", false, R, Z>, "cacheFirst">;
     /**
      * Sets the method to update.
      *
      * @param data - The data to update.
      * @returns filter options.
      */
-    update<Z = any>(data: R): SupastashFilterBuilder<"update", false, R, Z>;
+    update<Z = any>(data: R): Omit<SupastashFilterBuilder<"update", false, R, Z>, "cacheFirst" | "run" | "go" | "execute">;
     /**
      * Sets the method to delete.
      *
      * @returns filter options.
      */
-    delete<Z = any>(): SupastashFilterBuilder<"delete", false, R, Z>;
+    delete<Z = any>(): Omit<SupastashFilterBuilder<"delete", false, R, Z>, "cacheFirst">;
     /**
      * Sets the method to select.
      *
      * @param column - The column to select.
      * @returns filter options.
      */
-    select<Z = any>(column?: string): SupastashFilterBuilder<"select", false, R, Z>;
+    select<Z = any>(column?: string): Omit<SupastashFilterBuilder<"select", false, R, Z>, "withTx">;
     /**
      * Sets the method to upsert.
      *
@@ -59,6 +59,6 @@ export default class SupastashCrudBuilder<T extends CrudMethods, U extends boole
      */
     upsert<Z = any>(data: R | R[], options?: {
         onConflictKeys?: string[];
-    }): SupastashFilterBuilder<"upsert", false, R, Z>;
+    }): Omit<SupastashFilterBuilder<"upsert", false, R, Z>, "cacheFirst">;
 }
 //# sourceMappingURL=crud.d.ts.map

package/dist/shared/utils/query/builder/crud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crud.d.ts","sourceRoot":"","sources":["../../../../../src/shared/utils/query/builder/crud.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,sBAAsB,MAAM,WAAW,CAAC;AAE/C;;;;GAIG;AAEH,MAAM,CAAC,OAAO,OAAO,oBAAoB,CACvC,CAAC,SAAS,WAAW,EACrB,CAAC,SAAS,OAAO,EACjB,CAAC;IAMW,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJlC;;;OAGG;gBAC0B,KAAK,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAE3D;;;;;OAKG;IACH,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC,GAQhB,IAAI,CAAC,sBAAsB,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,YAAY,CAAC;IAGxE;;;;;OAKG;IACH,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC,GAQhB,IAAI,CACP,sBAAsB,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,EAC7C,YAAY,GAAG,KAAK,GAAG,IAAI,GAAG,SAAS,CACxC;IAGH;;;;OAIG;IACH,MAAM,CAAC,CAAC,GAAG,GAAG,KAOP,IAAI,CAAC,sBAAsB,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,YAAY,CAAC;IAGxE;;;;;OAKG;IACH,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,MAAM,CAAC,EAAE,MAAM,GAQxB,IAAI,CAAC,sBAAsB,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,QAAQ,CAAC;IAGpE;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAS/D,IAAI,CAAC,sBAAsB,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,YAAY,CAAC;CAEzE"}

package/dist/{utils → shared/utils}/query/builder/filters.d.ts

@@ -1,4 +1,5 @@
 import { CrudMethods, ExecuteOptions, SupastashQuery, SupastashQueryResult, SyncMode } from "../../../types/query.types";
+type FilterBuilderFor<T extends CrudMethods, U extends boolean, R, Z> = T extends "select" ? SupastashFilterBuilder<T, U, R, Z> : Omit<SupastashFilterBuilder<T, U, R, Z>, "cacheFirst">;
 /**
  * Builder for the filter methods
  * @param T - The method to call
@@ -30,7 +31,7 @@ export default class SupastashFilterBuilder<T extends CrudMethods, U extends boo
      * @param value - The value to filter by.
      * @returns more filter options.
      */
-    eq(column: string, value: any): SupastashFilterBuilder<T, U, R, Z>;
+    eq(column: string, value: any): FilterBuilderFor<T, U, R, Z>;
     /**
      * Sets the NEQ operator for the query.
      *
@@ -38,7 +39,7 @@ export default class SupastashFilterBuilder<T extends CrudMethods, U extends boo
      * @param value - The value to filter by.
      * @returns more filter options.
      */
-    neq(column: string, value: any): SupastashFilterBuilder<T, U, R, Z>;
+    neq(column: string, value: any): FilterBuilderFor<T, U, R, Z>;
     /**
      * Sets the GT operator for the query.
      *
@@ -46,7 +47,7 @@ export default class SupastashFilterBuilder<T extends CrudMethods, U extends boo
      * @param value - The value to filter by.
      * @returns more filter options.
      */
-    gt(column: string, value: any): SupastashFilterBuilder<T, U, R, Z>;
+    gt(column: string, value: any): FilterBuilderFor<T, U, R, Z>;
     /**
      * Sets the LT operator for the query.
      *
@@ -54,7 +55,7 @@ export default class SupastashFilterBuilder<T extends CrudMethods, U extends boo
      * @param value - The value to filter by.
      * @returns more filter options.
      */
-    lt(column: string, value: any): SupastashFilterBuilder<T, U, R, Z>;
+    lt(column: string, value: any): FilterBuilderFor<T, U, R, Z>;
     /**
      * Sets the GTE operator for the query.
      *
@@ -62,7 +63,7 @@ export default class SupastashFilterBuilder<T extends CrudMethods, U extends boo
      * @param value - The value to filter by.
      * @returns more filter options.
      */
-    gte(column: string, value: any): SupastashFilterBuilder<T, U, R, Z>;
+    gte(column: string, value: any): FilterBuilderFor<T, U, R, Z>;
     /**
      * Sets the LTE operator for the query.
      *
@@ -70,7 +71,7 @@ export default class SupastashFilterBuilder<T extends CrudMethods, U extends boo
      * @param value - The value to filter by.
      * @returns more filter options.
      */
-    lte(column: string, value: any): SupastashFilterBuilder<T, U, R, Z>;
+    lte(column: string, value: any): FilterBuilderFor<T, U, R, Z>;
     /**
      * Sets the LIKE operator for the query.
      *
@@ -78,7 +79,7 @@ export default class SupastashFilterBuilder<T extends CrudMethods, U extends boo
      * @param value - The value to filter by.
      * @returns more filter options.
      */
-    like(column: string, value: any): SupastashFilterBuilder<T, U, R, Z>;
+    like(column: string, value: any): FilterBuilderFor<T, U, R, Z>;
     /**
      * Sets the IS operator for the query.
      *
@@ -86,7 +87,7 @@ export default class SupastashFilterBuilder<T extends CrudMethods, U extends boo
      * @param value - The value to filter by.
      * @returns more filter options.
      */
-    is(column: string, value: any): SupastashFilterBuilder<T, U, R, Z>;
+    is(column: string, value: any): FilterBuilderFor<T, U, R, Z>;
     /**
      * Sets the IN operator for the query.
      *
@@ -94,14 +95,14 @@ export default class SupastashFilterBuilder<T extends CrudMethods, U extends boo
      * @param value - The value to filter by.
      * @returns more filter options.
      */
-    in(column: string, value: any[]): SupastashFilterBuilder<T, U, R, Z>;
+    in(column: string, value: any[]): FilterBuilderFor<T, U, R, Z>;
     /**
      * Sets the limit of the query.
      *
      * @param n - The number of results to return.
      * @returns more filter options.
      */
-    limit(n: number): SupastashFilterBuilder<T, U, R, Z>;
+    limit(n: number): FilterBuilderFor<T, U, R, Z>;
     /**
      * Returns only one result instead of an array.
      * Sets `limit(1)` automatically. Fails if more than one result is returned.
@@ -109,20 +110,42 @@ export default class SupastashFilterBuilder<T extends CrudMethods, U extends boo
      * Similar to Supabase `.single()`.
      */
     single(): SupastashFilterBuilder<T, true, R, Z>;
+    /**
+     * Creates its own SQLite transaction for this insert or upsert.
+     *
+     * Do not use inside `db.withTransaction(...)` or
+     * `supastash.withTransaction(...)` — nested transactions are not allowed.
+     */
+    withTx(): FilterBuilderFor<T, U, R, Z>;
     /**
      * Sets the preserve timestamp of the query.
      *
      * @param preserve - Whether to preserve the timestamp.
      * @returns more filter options.
      */
-    preserveTimestamp(preserve: boolean): SupastashFilterBuilder<T, U, R, Z>;
+    preserveTimestamp(preserve: boolean): FilterBuilderFor<T, U, R, Z>;
     /**
      * Sets the sync mode of the query.
      *
      * @param mode - The sync mode to use.
      * @returns more filter options.
      */
-    syncMode(mode: SyncMode): SupastashFilterBuilder<T, U, R, Z>;
+    syncMode(mode: SyncMode): FilterBuilderFor<T, U, R, Z>;
+    /**
+     * Throws an error if the query fails.
+     *
+     * @returns more filter options.
+     */
+    throwOnError(): FilterBuilderFor<T, U, R, Z>;
+    /**
+     * Executes a cache-first fetch strategy.
+     *
+     * Attempts to resolve the query from the local database.
+     * Falls back to the remote database if no usable result is found.
+     *
+     * @returns Query results from local and/or remote sources.
+     */
+    cacheFirst(): FilterBuilderFor<T, U, R, Z>;
     /**
      * Executes the query.
      * Must be called after all filters are set.
@@ -149,4 +172,5 @@ export default class SupastashFilterBuilder<T extends CrudMethods, U extends boo
         viewRemoteResult?: V;
     }): Promise<SupastashQueryResult<T, U, V, Z>>;
 }
+export {};
 //# sourceMappingURL=filters.d.ts.map

package/dist/shared/utils/query/builder/filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../../../../../src/shared/utils/query/builder/filters.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,cAAc,EAEd,cAAc,EACd,oBAAoB,EACpB,QAAQ,EACT,MAAM,4BAA4B,CAAC;AAKpC,KAAK,gBAAgB,CACnB,CAAC,SAAS,WAAW,EACrB,CAAC,SAAS,OAAO,EACjB,CAAC,EACD,CAAC,IACC,CAAC,SAAS,QAAQ,GAClB,sBAAsB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAClC,IAAI,CAAC,sBAAsB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;AAE3D;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,sBAAsB,CACzC,CAAC,SAAS,WAAW,EACrB,CAAC,SAAS,OAAO,EACjB,CAAC,EACD,CAAC;IAqCW,OAAO,CAAC,QAAQ,CAAC,KAAK;IAnClC;;;;OAIG;IACH,OAAO,CAAC,KAAK;IAYb;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAStB;;;OAGG;gBAC0B,KAAK,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAE3D;;;;;;OAMG;IACH,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG;IAI7B;;;;;;OAMG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG;IAI9B;;;;;;OAMG;IACH,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG;IAI7B;;;;;;OAMG;IACH,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG;IAI7B;;;;;;OAMG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG;IAI9B;;;;;;OAMG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG;IAI9B;;;;;;OAMG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG;IAI/B;;;;;;OAMG;IACH,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG;IAI7B;;;;;;OAMG;IACH,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE;IAI/B;;;;;OAKG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM;IAIf;;;;;OAKG;IACH,MAAM;IAQN;;;;;OAKG;IACH,MAAM;IAUN;;;;;OAKG;IACH,iBAAiB,CAAC,QAAQ,EAAE,OAAO;IAInC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ;IAIvB;;;;OAIG;IACH,YAAY;IAIZ;;;;;;;OAOG;IACH,UAAU;IAIV;;;;;OAKG;IACH,OAAO,CAAC,CAAC,SAAS,OAAO,GAAG,KAAK,EAC/B,OAAO,CAAC,EAAE,cAAc,GAAG;QAAE,gBAAgB,CAAC,EAAE,CAAC,CAAA;KAAE,GAClD,OAAO,CAAC,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IA4D5C;;;;OAIG;IACH,GAAG,CAAC,CAAC,SAAS,OAAO,GAAG,KAAK,EAC3B,OAAO,CAAC,EAAE,cAAc,GAAG;QAAE,gBAAgB,CAAC,EAAE,CAAC,CAAA;KAAE;IAKrD;;;;OAIG;IACH,EAAE,CAAC,CAAC,SAAS,OAAO,GAAG,KAAK,EAC1B,OAAO,CAAC,EAAE,cAAc,GAAG;QAAE,gBAAgB,CAAC,EAAE,CAAC,CAAA;KAAE;CAItD"}

package/dist/{utils → shared/utils}/query/builder/filters.js

@@ -1,4 +1,4 @@
-import log from "../../../utils/logs";
+import log from "../../logs";
 import { querySupabase } from "../remoteQuery/supabaseQuery";
 import { queryDb } from "./mainQuery";
 /**
@@ -151,6 +151,19 @@ export default class SupastashFilterBuilder {
             limit: 1,
         });
     }
+    /**
+     * Creates its own SQLite transaction for this insert or upsert.
+     *
+     * Do not use inside `db.withTransaction(...)` or
+     * `supastash.withTransaction(...)` — nested transactions are not allowed.
+     */
+    withTx() {
+        const isInATx = this.query.txId !== null;
+        if (isInATx) {
+            throw new Error(`[Supastash] Cannot use \`withTx()\` inside a transaction. Method: ${this.query.method} on table: ${this.query.table}`);
+        }
+        return this.withQueryPatch({ withTx: true });
+    }
     /**
      * Sets the preserve timestamp of the query.
      *
@@ -169,6 +182,25 @@ export default class SupastashFilterBuilder {
     syncMode(mode) {
         return this.withQueryPatch({ type: mode });
     }
+    /**
+     * Throws an error if the query fails.
+     *
+     * @returns more filter options.
+     */
+    throwOnError() {
+        return this.withQueryPatch({ throwOnError: true });
+    }
+    /**
+     * Executes a cache-first fetch strategy.
+     *
+     * Attempts to resolve the query from the local database.
+     * Falls back to the remote database if no usable result is found.
+     *
+     * @returns Query results from local and/or remote sources.
+     */
+    cacheFirst() {
+        return this.withQueryPatch({ fetchPolicy: "localFirst" });
+    }
     /**
      * Executes the query.
      * Must be called after all filters are set.

package/dist/{utils → shared/utils}/query/builder/index.d.ts

@@ -1,4 +1,4 @@
-import { CrudMethods, SupastashQuery } from "../../../types/query.types";
+import { CrudMethods, PayloadData, SupastashQuery } from "../../../types/query.types";
 import SupastashCrudBuilder from "./crud";
 /**
  * Builder for the supastash query
@@ -19,7 +19,34 @@ export declare class SupastashQueryBuilder<T extends CrudMethods, U extends bool
      * @returns crud options.
      */
     from(table: string): SupastashCrudBuilder<T, U, R>;
+    /**
+     * Executes multiple Supastash operations inside a single SQLite transaction.
+     *
+     * ⚠️ Do NOT call this inside `db.withTransaction(...)`
+     *  or another `supastash.withTransaction(...)`.
+     * Nested transactions are not supported and will throw.
+     *
+     * All queries executed using the provided `tx` builder
+     * will share the same SQLite transaction and `txId`.
+     *
+     * If any operation inside the callback throws,
+     * the entire transaction is rolled back automatically.
+     *
+     * Example:
+     *
+     * await supastash.withTransaction(async (tx) => {
+     *   await tx.from("orders").insert(order).run();
+     *   await tx.from("ledger").insert(ledgerEntry).run();
+     * });
+     *
+     *
+     * In this example, both inserts succeed or both fail.
+     */
+    withTransaction(fn: (tx: SupastashTransactionalBuilder<T, U, R>) => Promise<void> | void): Promise<void>;
 }
+type SupastashTransactionalBuilder<T extends CrudMethods, U extends boolean, R> = Omit<SupastashQueryBuilder<T, U, R>, "withTransaction">;
+export type SupastashTransactionClient = SupastashTransactionalBuilder<CrudMethods, boolean, PayloadData>;
+export type SupastashClient = SupastashTransactionalBuilder<CrudMethods, boolean, PayloadData>;
 /**
  * Supastash query builder for local-first CRUD operations.
  *
@@ -42,4 +69,5 @@ export declare class SupastashQueryBuilder<T extends CrudMethods, U extends bool
  *   .run(); // Required to execute the query
  */
 export declare const supastash: SupastashQueryBuilder<CrudMethods, boolean, any>;
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/shared/utils/query/builder/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/shared/utils/query/builder/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,WAAW,EAEX,WAAW,EACX,cAAc,EAEf,MAAM,4BAA4B,CAAC;AAGpC,OAAO,oBAAoB,MAAM,QAAQ,CAAC;AAE1C;;;;GAIG;AACH,qBAAa,qBAAqB,CAChC,CAAC,SAAS,WAAW,EACrB,CAAC,SAAS,OAAO,EACjB,CAAC;IAED,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAEhD;;;OAGG;gBACS,KAAK,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAI1C;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM;IAOlB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,eAAe,CACb,EAAE,EAAE,CAAC,EAAE,EAAE,6BAA6B,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;CAgD3E;AAED,KAAK,6BAA6B,CAChC,CAAC,SAAS,WAAW,EACrB,CAAC,SAAS,OAAO,EACjB,CAAC,IACC,IAAI,CAAC,qBAAqB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC;AAE5D,MAAM,MAAM,0BAA0B,GAAG,6BAA6B,CACpE,WAAW,EACX,OAAO,EACP,WAAW,CACZ,CAAC;AACF,MAAM,MAAM,eAAe,GAAG,6BAA6B,CACzD,WAAW,EACX,OAAO,EACP,WAAW,CACZ,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,SAAS,kDAyBiC,CAAC"}

package/dist/shared/utils/query/builder/index.js

@@ -0,0 +1,138 @@
+import { getSupastashDb } from "../../../db/dbInitializer";
+import { txStore } from "../../../store/tx";
+import { generateUUIDv4 } from "../../genUUID";
+import { queueRemoteCall } from "../helpers/queueRemote";
+import SupastashCrudBuilder from "./crud";
+/**
+ * Builder for the supastash query
+ * @param T - The method to call
+ * @param U - Whether to return a single row or multiple rows
+ */
+export class SupastashQueryBuilder {
+    /**
+     * Constructor for the supastash query builder
+     * @param query - The query to build
+     */
+    constructor(query) {
+        this.query = query;
+    }
+    /**
+     * Sets the table to query.
+     *
+     * @param table - The table to query.
+     * @returns crud options.
+     */
+    from(table) {
+        const id = generateUUIDv4();
+        const newQuery = { ...this.query, table, id };
+        return new SupastashCrudBuilder(newQuery);
+    }
+    /**
+     * Executes multiple Supastash operations inside a single SQLite transaction.
+     *
+     * ⚠️ Do NOT call this inside `db.withTransaction(...)`
+     *  or another `supastash.withTransaction(...)`.
+     * Nested transactions are not supported and will throw.
+     *
+     * All queries executed using the provided `tx` builder
+     * will share the same SQLite transaction and `txId`.
+     *
+     * If any operation inside the callback throws,
+     * the entire transaction is rolled back automatically.
+     *
+     * Example:
+     *
+     * await supastash.withTransaction(async (tx) => {
+     *   await tx.from("orders").insert(order).run();
+     *   await tx.from("ledger").insert(ledgerEntry).run();
+     * });
+     *
+     *
+     * In this example, both inserts succeed or both fail.
+     */
+    withTransaction(fn) {
+        const query = async () => {
+            // Create a new transaction id
+            const newTxId = generateUUIDv4();
+            try {
+                const db = await getSupastashDb();
+                // Add the transaction to the store
+                txStore[newTxId] = [];
+                // Execute the local calls
+                await db.withTransaction(async (tx) => {
+                    const txQuery = {
+                        ...this.query,
+                        txId: newTxId,
+                        tx,
+                        throwOnError: true, // Throw the error to roll back the transaction
+                    };
+                    const txBuilder = new SupastashQueryBuilder(txQuery);
+                    return fn(txBuilder);
+                });
+                // Execute the remote calls
+                const remoteCalls = txStore[newTxId] ?? [];
+                if (remoteCalls.length > 0) {
+                    const newStates = remoteCalls.map((call) => {
+                        return {
+                            ...call,
+                            txId: null,
+                            tx: null,
+                            withTx: false,
+                            type: "remoteOnly",
+                        };
+                    });
+                    for (const state of newStates) {
+                        queueRemoteCall(state);
+                    }
+                }
+            }
+            finally {
+                // Delete the transaction from the store
+                delete txStore[newTxId];
+            }
+        };
+        return query();
+    }
+}
+/**
+ * Supastash query builder for local-first CRUD operations.
+ *
+ * This builder allows you to construct and execute queries against a local SQLite store
+ * with optional synchronization to Supabase.
+ *
+ * Notes:
+ * - SELECT operations return local data by default unless `sync mode` is set to "remoteOnly".
+ * - `.run()` (alias of `.execute()`) is **required** to finalize and perform the query.
+ * - Use `.run({ viewRemoteResult: true })` to view the remote result from Supabase.
+ * - All operations except DELETE return local data automatically — no need to chain `.select()`.
+ *
+ * @returns A chainable Supastash query instance.
+ *
+ * @example
+ * const result = await supastash
+ *   .from("users")
+ *   .update<T>({ name: "John Doe" })
+ *   .eq("id", "1")
+ *   .run(); // Required to execute the query
+ */
+export const supastash = new SupastashQueryBuilder({
+    id: generateUUIDv4(),
+    table: "",
+    method: "none",
+    payload: null,
+    filters: [],
+    limit: null,
+    select: null,
+    isSingle: false,
+    type: "localFirst",
+    runSelected: false,
+    viewRemoteResult: false,
+    onConflictKeys: ["id"],
+    preserveTimestamp: false,
+    throwOnError: false,
+    fetchPolicy: null,
+    // With tx
+    txId: null,
+    tx: null,
+    withTx: false,
+});

package/dist/shared/utils/query/builder/mainQuery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mainQuery.d.ts","sourceRoot":"","sources":["../../../../../src/shared/utils/query/builder/mainQuery.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,WAAW,EAGX,cAAc,EACd,oBAAoB,EAErB,MAAM,4BAA4B,CAAC;AAWpC;;;;GAIG;AACH,wBAAsB,OAAO,CAC3B,CAAC,SAAS,WAAW,EACrB,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO,EACjB,CAAC,EACD,CAAC,EAED,KAAK,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG;IAAE,gBAAgB,EAAE,CAAC,CAAA;CAAE,GACvD,OAAO,CAAC,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAiG3C"}