nexabase-console 2.1.2 → 2.1.3

package/dist/firestore/Timestamp.js

@@ -1,20 +1,41 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Timestamp = void 0;
+const NexaError_1 = require("../errors/NexaError");
+const MIN_SECONDS = -62135596800; // 0001-01-01T00:00:00Z
+const MAX_SECONDS = 253402300799; // 9999-12-31T23:59:59Z
 class Timestamp {
     constructor(seconds, nanoseconds) {
+        if (!Number.isSafeInteger(seconds) || seconds < MIN_SECONDS || seconds > MAX_SECONDS) {
+            throw new NexaError_1.NexaError('invalid-argument', `Timestamp seconds must be a safe integer between ${MIN_SECONDS} and ${MAX_SECONDS}, but got ${seconds}.`);
+        }
+        if (!Number.isSafeInteger(nanoseconds) || nanoseconds < 0 || nanoseconds > 999999999) {
+            throw new NexaError_1.NexaError('invalid-argument', `Timestamp nanoseconds must be a non-negative safe integer less than 1,000,000,000, but got ${nanoseconds}.`);
+        }
         this.seconds = seconds;
         this.nanoseconds = nanoseconds;
+        Object.freeze(this);
     }
     static now() {
         return Timestamp.fromMillis(Date.now());
     }
     static fromDate(date) {
+        if (!(date instanceof Date) || isNaN(date.getTime())) {
+            throw new NexaError_1.NexaError('invalid-argument', 'Timestamp.fromDate() expects a valid Date object.');
+        }
         return Timestamp.fromMillis(date.getTime());
     }
     static fromMillis(milliseconds) {
-        const seconds = Math.floor(milliseconds / 1000);
-        const nanoseconds = Math.floor((milliseconds % 1000) * 1e6);
+        if (typeof milliseconds !== 'number' || !Number.isFinite(milliseconds)) {
+            throw new NexaError_1.NexaError('invalid-argument', 'Timestamp.fromMillis() expects a finite number.');
+        }
+        let seconds = Math.floor(milliseconds / 1000);
+        const remainderMs = milliseconds - seconds * 1000;
+        let nanoseconds = Math.round(remainderMs * 1e6);
+        if (nanoseconds >= 1e9) {
+            seconds += 1;
+            nanoseconds = 0;
+        }
         return new Timestamp(seconds, nanoseconds);
     }
     toDate() {
@@ -24,8 +45,13 @@ class Timestamp {
         return this.seconds * 1000 + Math.floor(this.nanoseconds / 1e6);
     }
     isEqual(other) {
+        if (!(other instanceof Timestamp))
+            return false;
         return this.seconds === other.seconds && this.nanoseconds === other.nanoseconds;
     }
+    valueOf() {
+        return this.toString();
+    }
     toString() {
         return `Timestamp(seconds=${this.seconds}, nanoseconds=${this.nanoseconds})`;
     }

package/dist/firestore/batch.js

@@ -3,32 +3,90 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.writeBatch = void 0;
 const helpers_1 = require("../utils/helpers");
 const NexaError_1 = require("../errors/NexaError");
+const QueryUtils_1 = require("./QueryUtils");
+const pathValidation_1 = require("./pathValidation");
 const writeBatch = (db) => {
+    if (!db) {
+        throw new NexaError_1.NexaError('invalid-argument', 'writeBatch requires a valid NexaApp database instance.');
+    }
     const operations = [];
+    let committed = false;
     const batchObj = {
-        set: (docRef, data) => {
-            operations.push({ type: 'set', path: docRef.path, data });
+        set: (docRef, data, options) => {
+            if (committed) {
+                throw new NexaError_1.NexaError('failed-precondition', 'A WriteBatch cannot be modified after commit() has been called.');
+            }
+            if (!docRef || !docRef.path) {
+                throw new NexaError_1.NexaError('invalid-argument', 'WriteBatch.set() requires a valid DocumentReference.');
+            }
+            (0, pathValidation_1.validateDocumentPath)(docRef.path);
+            if (!data || typeof data !== 'object' || Array.isArray(data)) {
+                throw new NexaError_1.NexaError('invalid-argument', 'WriteBatch.set() data must be a plain object.');
+            }
+            if (operations.length >= 500) {
+                throw new NexaError_1.NexaError('invalid-argument', 'A WriteBatch cannot contain more than 500 operations.');
+            }
+            operations.push({
+                type: 'set',
+                path: docRef.path,
+                data: (0, QueryUtils_1.cloneNexaData)(data),
+                options
+            });
             return batchObj;
         },
         update: (docRef, data) => {
-            operations.push({ type: 'update', path: docRef.path, data });
+            if (committed) {
+                throw new NexaError_1.NexaError('failed-precondition', 'A WriteBatch cannot be modified after commit() has been called.');
+            }
+            if (!docRef || !docRef.path) {
+                throw new NexaError_1.NexaError('invalid-argument', 'WriteBatch.update() requires a valid DocumentReference.');
+            }
+            (0, pathValidation_1.validateDocumentPath)(docRef.path);
+            if (!data || typeof data !== 'object' || Array.isArray(data)) {
+                throw new NexaError_1.NexaError('invalid-argument', 'WriteBatch.update() data must be a plain object.');
+            }
+            if (operations.length >= 500) {
+                throw new NexaError_1.NexaError('invalid-argument', 'A WriteBatch cannot contain more than 500 operations.');
+            }
+            operations.push({
+                type: 'update',
+                path: docRef.path,
+                data: (0, QueryUtils_1.cloneNexaData)(data)
+            });
             return batchObj;
         },
         patch: (docRef, data) => {
-            operations.push({ type: 'update', path: docRef.path, data });
-            return batchObj;
+            return batchObj.update(docRef, data);
         },
         delete: (docRef) => {
-            operations.push({ type: 'delete', path: docRef.path });
+            if (committed) {
+                throw new NexaError_1.NexaError('failed-precondition', 'A WriteBatch cannot be modified after commit() has been called.');
+            }
+            if (!docRef || !docRef.path) {
+                throw new NexaError_1.NexaError('invalid-argument', 'WriteBatch.delete() requires a valid DocumentReference.');
+            }
+            (0, pathValidation_1.validateDocumentPath)(docRef.path);
+            if (operations.length >= 500) {
+                throw new NexaError_1.NexaError('invalid-argument', 'A WriteBatch cannot contain more than 500 operations.');
+            }
+            operations.push({
+                type: 'delete',
+                path: docRef.path
+            });
             return batchObj;
         },
         commit: async () => {
+            if (committed) {
+                throw new NexaError_1.NexaError('failed-precondition', 'A WriteBatch cannot be committed more than once.');
+            }
+            committed = true;
             if (db._initPromise)
                 await db._initPromise;
             if (operations.length === 0)
                 return;
             const idempotencyKey = (0, helpers_1.generateIdempotencyKey)();
             const isOnline = typeof navigator !== 'undefined' ? navigator.onLine : true;
+            // 1. Optimistic Local Commit
             for (const op of operations) {
                 if (op.type === 'set' || op.type === 'update') {
                     const newData = (0, helpers_1.applyDataTransforms)(db._firestoreCache[op.path] || {}, op.data);
@@ -42,39 +100,34 @@ const writeBatch = (db) => {
                     db._notifySnapshotCallbacks(op.path, 'document_deleted', null);
                 }
             }
+            // 2. Offline Queue Persistence
+            for (const op of operations) {
+                await db._addOfflineJob({
+                    id: `${idempotencyKey}_${op.path.replace(/\//g, '_')}`,
+                    type: op.type === 'update' ? 'patch' : op.type,
+                    path: op.path,
+                    data: op.data,
+                    idempotencyKey,
+                    merge: op.options?.merge,
+                    state: 'pending'
+                });
+            }
             if (!isOnline) {
-                for (const op of operations) {
-                    await db._addOfflineJob({
-                        id: Math.random().toString(36).substring(2, 9),
-                        type: op.type,
-                        path: op.path,
-                        data: op.data,
-                        idempotencyKey,
-                        state: 'pending'
-                    });
-                }
-                return { success: true, message: 'Offline: Batch operations queued in IndexedDB' };
+                return { success: true, message: 'Offline: Batch operations queued for sync' };
             }
-            else {
-                try {
-                    return (await db.client.post(`/api/firestore/${db.projectId}/batch`, { operations, idempotencyKey }, { headers: { 'X-Idempotency-Key': idempotencyKey } })).data;
-                }
-                catch (error) {
-                    if (error && error.response && error.response.status >= 400 && error.response.status < 500) {
-                        throw (0, NexaError_1.toNexaError)(error);
-                    }
-                    for (const op of operations) {
-                        await db._addOfflineJob({
-                            id: Math.random().toString(36).substring(2, 9),
-                            type: op.type,
-                            path: op.path,
-                            data: op.data,
-                            idempotencyKey,
-                            state: 'pending'
-                        });
-                    }
-                    return { success: true, message: 'Koneksi terganggu: Tersimpan di antrean offline' };
+            // 3. Online Server Sync
+            try {
+                const response = await db.client.post(`/api/firestore/${db.projectId}/batch`, { operations, idempotencyKey }, { headers: { 'X-Idempotency-Key': idempotencyKey } });
+                return response.data;
+            }
+            catch (error) {
+                const status = error?.response?.status;
+                const isClientError = status && status >= 400 && status < 500 && status !== 408 && status !== 429;
+                if (isClientError) {
+                    throw (0, NexaError_1.toNexaError)(error);
                 }
+                // Retryable/network error: keep in offline queue
+                return { success: true, message: 'Network disrupted: batch queued offline' };
             }
         }
     };

package/dist/firestore/pathValidation.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Validates raw path string and extracts clean segments.
+ * Throws NexaError('invalid-argument') on any validation failure.
+ */
+export declare function validatePathSegments(path: string): string[];
+/**
+ * Validates that a path points to a valid collection (odd number of segments).
+ */
+export declare function validateCollectionPath(path: string): string;
+/**
+ * Validates that a path points to a valid document (even number of segments).
+ */
+export declare function validateDocumentPath(path: string): string;
+/**
+ * Generates a 20-character alphanumeric auto-ID matching Firestore specifications.
+ */
+export declare function generateAutoId(): string;

package/dist/firestore/pathValidation.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePathSegments = validatePathSegments;
+exports.validateCollectionPath = validateCollectionPath;
+exports.validateDocumentPath = validateDocumentPath;
+exports.generateAutoId = generateAutoId;
+const NexaError_1 = require("../errors/NexaError");
+const CONTROL_CHARS_REGEX = /[\x00-\x1F\x7F]/;
+/**
+ * Validates raw path string and extracts clean segments.
+ * Throws NexaError('invalid-argument') on any validation failure.
+ */
+function validatePathSegments(path) {
+    if (typeof path !== 'string' || path.length === 0) {
+        throw new NexaError_1.NexaError('invalid-argument', 'Path must be a non-empty string.');
+    }
+    if (CONTROL_CHARS_REGEX.test(path)) {
+        throw new NexaError_1.NexaError('invalid-argument', 'Path contains invalid control characters.');
+    }
+    if (path.startsWith('/') || path.endsWith('/') || path.includes('//')) {
+        throw new NexaError_1.NexaError('invalid-argument', 'Path must not contain empty segments or leading/trailing slashes.');
+    }
+    const segments = path.split('/');
+    for (const seg of segments) {
+        if (!seg || seg.trim().length === 0) {
+            throw new NexaError_1.NexaError('invalid-argument', 'Path segment cannot be empty or whitespace-only.');
+        }
+    }
+    return segments;
+}
+/**
+ * Validates that a path points to a valid collection (odd number of segments).
+ */
+function validateCollectionPath(path) {
+    const segments = validatePathSegments(path);
+    if (segments.length % 2 === 0) {
+        throw new NexaError_1.NexaError('invalid-argument', `Invalid collection path (${path}). Collection paths must have an odd number of segments.`);
+    }
+    return segments.join('/');
+}
+/**
+ * Validates that a path points to a valid document (even number of segments).
+ */
+function validateDocumentPath(path) {
+    const segments = validatePathSegments(path);
+    if (segments.length % 2 !== 0) {
+        throw new NexaError_1.NexaError('invalid-argument', `Invalid document path (${path}). Document paths must have an even number of segments.`);
+    }
+    return segments.join('/');
+}
+/**
+ * Generates a 20-character alphanumeric auto-ID matching Firestore specifications.
+ */
+function generateAutoId() {
+    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+    let autoId = '';
+    for (let i = 0; i < 20; i++) {
+        autoId += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return autoId;
+}

package/dist/firestore/queryConstraints.d.ts

@@ -3,7 +3,7 @@ import { QueryConstraint, WhereFilterOp } from '../types/index';
 export declare const where: (fieldPath: string | FieldPath, opStr: WhereFilterOp | string, value: any) => QueryConstraint;
 export declare const orderBy: (fieldPath: string | FieldPath, directionStr?: "asc" | "desc") => QueryConstraint;
 export declare const limit: (limitValue: number) => QueryConstraint;
-export declare const startAt: (docSnapshot: any) => QueryConstraint;
-export declare const startAfter: (docSnapshot: any) => QueryConstraint;
-export declare const endAt: (docSnapshot: any) => QueryConstraint;
-export declare const endBefore: (docSnapshot: any) => QueryConstraint;
+export declare const startAt: (...docSnapshotOrValues: any[]) => QueryConstraint;
+export declare const startAfter: (...docSnapshotOrValues: any[]) => QueryConstraint;
+export declare const endAt: (...docSnapshotOrValues: any[]) => QueryConstraint;
+export declare const endBefore: (...docSnapshotOrValues: any[]) => QueryConstraint;

package/dist/firestore/queryConstraints.js

@@ -1,31 +1,92 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.endBefore = exports.endAt = exports.startAfter = exports.startAt = exports.limit = exports.orderBy = exports.where = void 0;
+const FieldPath_1 = require("./FieldPath");
+const NexaError_1 = require("../errors/NexaError");
+const VALID_WHERE_OPS = new Set([
+    '<',
+    '<=',
+    '==',
+    '!=',
+    '>=',
+    '>',
+    'array-contains',
+    'array-contains-any',
+    'in',
+    'not-in'
+]);
+function validateFieldPath(fieldPath) {
+    if (!fieldPath) {
+        throw new NexaError_1.NexaError('invalid-argument', 'Field path cannot be empty.');
+    }
+    if (typeof fieldPath !== 'string' && !(fieldPath instanceof FieldPath_1.FieldPath)) {
+        throw new NexaError_1.NexaError('invalid-argument', 'Field path must be a non-empty string or FieldPath instance.');
+    }
+    if (typeof fieldPath === 'string' && fieldPath.trim().length === 0) {
+        throw new NexaError_1.NexaError('invalid-argument', 'Field path string cannot be empty or whitespace.');
+    }
+}
 const where = (fieldPath, opStr, value) => {
+    validateFieldPath(fieldPath);
+    if (!VALID_WHERE_OPS.has(opStr)) {
+        throw new NexaError_1.NexaError('invalid-argument', `Invalid query operator '${opStr}'. Valid operators are: ${Array.from(VALID_WHERE_OPS).join(', ')}`);
+    }
+    if (opStr === 'in' || opStr === 'not-in' || opStr === 'array-contains-any') {
+        if (!Array.isArray(value)) {
+            throw new NexaError_1.NexaError('invalid-argument', `Query operator '${opStr}' requires an array value, but got ${typeof value}.`);
+        }
+        if (value.length === 0) {
+            throw new NexaError_1.NexaError('invalid-argument', `Query operator '${opStr}' requires a non-empty array.`);
+        }
+        if (value.length > 30) {
+            throw new NexaError_1.NexaError('invalid-argument', `Query operator '${opStr}' supports at most 30 elements in array filter.`);
+        }
+    }
     return { type: 'where', fieldPath, opStr, value };
 };
 exports.where = where;
 const orderBy = (fieldPath, directionStr = 'asc') => {
+    validateFieldPath(fieldPath);
+    if (directionStr !== 'asc' && directionStr !== 'desc') {
+        throw new NexaError_1.NexaError('invalid-argument', `Invalid orderBy direction '${directionStr}'. Must be 'asc' or 'desc'.`);
+    }
     return { type: 'orderBy', fieldPath, directionStr };
 };
 exports.orderBy = orderBy;
 const limit = (limitValue) => {
+    if (typeof limitValue !== 'number' || !Number.isSafeInteger(limitValue) || limitValue <= 0) {
+        throw new NexaError_1.NexaError('invalid-argument', `limit() value must be a positive safe integer, but got ${limitValue}.`);
+    }
     return { type: 'limit', limitValue };
 };
 exports.limit = limit;
-const startAt = (docSnapshot) => {
-    return { type: 'startAt', docSnapshot };
+const createCursorConstraint = (type, docSnapshotOrValues) => {
+    if (!docSnapshotOrValues || docSnapshotOrValues.length === 0) {
+        throw new NexaError_1.NexaError('invalid-argument', `${type}() requires at least one argument (DocumentSnapshot or field values).`);
+    }
+    const firstArg = docSnapshotOrValues[0];
+    const isSnapshot = firstArg &&
+        typeof firstArg === 'object' &&
+        typeof firstArg.id === 'string' &&
+        (typeof firstArg.data === 'function' || typeof firstArg.exists === 'function');
+    if (isSnapshot && docSnapshotOrValues.length === 1) {
+        return { type, docSnapshot: firstArg };
+    }
+    return { type, cursorValues: docSnapshotOrValues };
+};
+const startAt = (...docSnapshotOrValues) => {
+    return createCursorConstraint('startAt', docSnapshotOrValues);
 };
 exports.startAt = startAt;
-const startAfter = (docSnapshot) => {
-    return { type: 'startAfter', docSnapshot };
+const startAfter = (...docSnapshotOrValues) => {
+    return createCursorConstraint('startAfter', docSnapshotOrValues);
 };
 exports.startAfter = startAfter;
-const endAt = (docSnapshot) => {
-    return { type: 'endAt', docSnapshot };
+const endAt = (...docSnapshotOrValues) => {
+    return createCursorConstraint('endAt', docSnapshotOrValues);
 };
 exports.endAt = endAt;
-const endBefore = (docSnapshot) => {
-    return { type: 'endBefore', docSnapshot };
+const endBefore = (...docSnapshotOrValues) => {
+    return createCursorConstraint('endBefore', docSnapshotOrValues);
 };
 exports.endBefore = endBefore;

package/dist/firestore/transaction.js

@@ -5,56 +5,110 @@ const SnapshotManager_1 = require("./SnapshotManager");
 const ConflictResolver_1 = require("../sync/ConflictResolver");
 const NexaError_1 = require("../errors/NexaError");
 const helpers_1 = require("../utils/helpers");
+const QueryUtils_1 = require("./QueryUtils");
+const pathValidation_1 = require("./pathValidation");
 const runTransaction = async (db, updateFunction, options) => {
+    if (!db) {
+        throw new NexaError_1.NexaError('invalid-argument', 'runTransaction requires a valid NexaApp database instance.');
+    }
+    if (typeof updateFunction !== 'function') {
+        throw new NexaError_1.NexaError('invalid-argument', 'updateFunction must be a valid function.');
+    }
     if (db._initPromise)
         await db._initPromise;
+    const maxAttempts = options?.maxAttempts ?? 5;
     return ConflictResolver_1.ConflictResolver.resolveWithRetry(async () => {
         const reads = [];
         const operations = [];
+        let writesStarted = false;
         const idempotencyKey = (0, helpers_1.generateIdempotencyKey)();
         const transaction = {
             get: async (docRef) => {
-                let res;
+                if (writesStarted) {
+                    throw new NexaError_1.NexaError('failed-precondition', 'Firestore transactions require all reads to be executed before all writes.');
+                }
+                if (!docRef || !docRef.path) {
+                    throw new NexaError_1.NexaError('invalid-argument', 'Transaction.get() requires a valid DocumentReference.');
+                }
+                (0, pathValidation_1.validateDocumentPath)(docRef.path);
+                if (typeof navigator !== 'undefined' && !navigator.onLine) {
+                    throw new NexaError_1.NexaError('unavailable', 'Transaction failed: Client is offline. Transactions require an active server connection.');
+                }
                 try {
-                    if (typeof navigator !== 'undefined' && !navigator.onLine) {
-                        throw Object.assign(new Error('NEXA_ERR_TRANSACTION_OFFLINE'), { code: 'NEXA_ERR_TRANSACTION_OFFLINE' });
-                    }
-                    res = await db.client.get(`/api/firestore/${db.projectId}/documentWithMetadata?docPath=${encodeURIComponent(docRef.path)}`);
+                    const res = await db.client.get(`/api/firestore/${db.projectId}/documentWithMetadata?docPath=${encodeURIComponent(docRef.path)}`);
+                    const { data, updatedAt } = res.data;
+                    reads.push({ path: docRef.path, readUpdatedAt: updatedAt ?? null });
+                    return SnapshotManager_1.SnapshotManager.createDocumentSnapshot(docRef, (data ?? null), false, db.hasPendingWrites(docRef.path));
                 }
                 catch (err) {
-                    if (err?.code === 'NEXA_ERR_TRANSACTION_OFFLINE' || err?.message === 'NEXA_ERR_TRANSACTION_OFFLINE') {
-                        throw Object.assign(new Error('Transaction failed: Perangkat sedang offline atau jaringan terputus. Transaksi memerlukan koneksi aktif. Gunakan writeBatch atau runOfflineSafeTransaction untuk operasi offline.'), { code: 'NEXA_ERR_TRANSACTION_OFFLINE' });
+                    if (err?.response?.status === 404) {
+                        reads.push({ path: docRef.path, readUpdatedAt: null });
+                        return SnapshotManager_1.SnapshotManager.createDocumentSnapshot(docRef, null, false, false);
                     }
                     throw (0, NexaError_1.toNexaError)(err);
                 }
-                const { data, updatedAt } = res.data;
-                reads.push({ path: docRef.path, readUpdatedAt: updatedAt });
-                return SnapshotManager_1.SnapshotManager.createDocumentSnapshot(docRef, data, false, db.hasPendingWrites(docRef.path));
             },
             set: (docRef, data) => {
-                operations.push({ type: 'set', path: docRef.path, data });
+                if (!docRef || !docRef.path) {
+                    throw new NexaError_1.NexaError('invalid-argument', 'Transaction.set() requires a valid DocumentReference.');
+                }
+                (0, pathValidation_1.validateDocumentPath)(docRef.path);
+                if (!data || typeof data !== 'object' || Array.isArray(data)) {
+                    throw new NexaError_1.NexaError('invalid-argument', 'Transaction.set() data must be a plain object.');
+                }
+                writesStarted = true;
+                operations.push({
+                    type: 'set',
+                    path: docRef.path,
+                    data: (0, QueryUtils_1.cloneNexaData)(data)
+                });
                 return transaction;
             },
             update: (docRef, data) => {
-                operations.push({ type: 'update', path: docRef.path, data });
+                if (!docRef || !docRef.path) {
+                    throw new NexaError_1.NexaError('invalid-argument', 'Transaction.update() requires a valid DocumentReference.');
+                }
+                (0, pathValidation_1.validateDocumentPath)(docRef.path);
+                if (!data || typeof data !== 'object' || Array.isArray(data)) {
+                    throw new NexaError_1.NexaError('invalid-argument', 'Transaction.update() data must be a plain object.');
+                }
+                writesStarted = true;
+                operations.push({
+                    type: 'update',
+                    path: docRef.path,
+                    data: (0, QueryUtils_1.cloneNexaData)(data)
+                });
                 return transaction;
             },
             patch: (docRef, data) => {
-                operations.push({ type: 'update', path: docRef.path, data });
-                return transaction;
+                return transaction.update(docRef, data);
             },
             delete: (docRef) => {
-                operations.push({ type: 'delete', path: docRef.path });
+                if (!docRef || !docRef.path) {
+                    throw new NexaError_1.NexaError('invalid-argument', 'Transaction.delete() requires a valid DocumentReference.');
+                }
+                (0, pathValidation_1.validateDocumentPath)(docRef.path);
+                writesStarted = true;
+                operations.push({
+                    type: 'delete',
+                    path: docRef.path
+                });
                 return transaction;
             }
         };
         const result = await updateFunction(transaction);
         if (operations.length > 0 || reads.length > 0) {
             if (typeof navigator !== 'undefined' && !navigator.onLine) {
-                throw Object.assign(new Error('Transaction failed: Perangkat sedang offline atau jaringan terputus. Transaksi memerlukan koneksi aktif. Gunakan writeBatch atau runOfflineSafeTransaction untuk operasi offline.'), { code: 'NEXA_ERR_TRANSACTION_OFFLINE' });
+                throw new NexaError_1.NexaError('unavailable', 'Transaction failed: Client is offline. Transactions require an active server connection.');
+            }
+            try {
+                await db.client.post(`/api/firestore/${db.projectId}/transaction`, { reads, operations, idempotencyKey }, { headers: { 'X-Idempotency-Key': idempotencyKey } });
+            }
+            catch (err) {
+                throw (0, NexaError_1.toNexaError)(err);
             }
-            await db.client.post(`/api/firestore/${db.projectId}/transaction`, { reads, operations, idempotencyKey }, { headers: { 'X-Idempotency-Key': idempotencyKey } });
         }
+        // Atomic local commit after successful server transaction
         for (const op of operations) {
             if (op.type === 'set' || op.type === 'update') {
                 const newData = (0, helpers_1.applyDataTransforms)(db._firestoreCache[op.path] || {}, op.data);
@@ -69,6 +123,6 @@ const runTransaction = async (db, updateFunction, options) => {
             }
         }
         return result;
-    }, options?.maxAttempts ?? 5);
+    }, maxAttempts);
 };
 exports.runTransaction = runTransaction;

package/dist/firestore/writes.d.ts

@@ -1,4 +1,4 @@
-import { NexaApp } from "../app/NexaApp";
+import { NexaApp } from '../app/NexaApp';
 import { DocumentReference } from '../types/index';
 export { FieldValue } from './FieldValue';
 export type WriteResult<T = unknown> = {