Firestore Mutations

firekitMutations is a stateless service for writing to Firestore. All methods are async and return a promise.

import { firekitMutations } from 'svelte-firekit';

Basic CRUD

// Add a document with a generated ID
const ref = await firekitMutations.add('posts', { title: 'Hello World', published: false });

// Set a document (overwrites if it exists)
await firekitMutations.set('posts/my-post-id', { title: 'Hello World', published: false });

// Update specific fields (merges, does not overwrite)
await firekitMutations.update('posts/my-post-id', { title: 'Updated Title' });

// Delete a document
await firekitMutations.delete('posts/my-post-id');

// Check if a document exists
const exists = await firekitMutations.exists('posts/my-post-id');

Field value helpers

Use these helpers inside add, set, and update calls to apply atomic server-side operations:

await firekitMutations.update('posts/my-post-id', {
  views:     firekitMutations.increment(1),           // atomic counter increment
  tags:      firekitMutations.arrayUnion('svelte'),   // add to array (no duplicates)
  oldTags:   firekitMutations.arrayRemove('legacy'),  // remove from array
  draft:     firekitMutations.deleteField(),          // remove a field entirely
  updatedAt: firekitMutations.serverTimestamp(),      // server-side timestamp
});

Helper	Description
increment(n)	Atomically increment / decrement a numeric field
arrayUnion(...values)	Add values to an array field (deduplicates)
arrayRemove(...values)	Remove values from an array field
deleteField()	Remove a field from the document
serverTimestamp()	Set a field to the server’s current time

Timestamps option

Pass { timestamps: true } to automatically add createdAt and updatedAt fields:

await firekitMutations.add('posts', { title: 'Hello' }, { timestamps: true, userId: uid });
// result document: { title: 'Hello', createdAt: Timestamp, updatedAt: Timestamp, createdBy: uid }

The userId field is stored as createdBy on add and updatedBy on update.

Retry on failure

await firekitMutations.set('posts/id', data, {
  retry: {
    enabled: true,
    maxAttempts: 3,
    baseDelay: 200,            // ms
    strategy: 'exponential',  // 'fixed' | 'exponential'
  },
});

Batch writes

batchOps accepts an array of operations and automatically splits them into chunks of 500 (Firestore’s batch limit).

import type { FirekitBatchOp } from 'svelte-firekit';

const ops: FirekitBatchOp[] = [
  { type: 'set',    path: 'posts',    id: 'post-a', data: { title: 'Post A' } },
  { type: 'update', path: 'posts/post-b',           data: { views: 10 } },
  { type: 'delete', path: 'posts/post-c' },
];

const result = await firekitMutations.batchOps(ops);
// result.success, result.count

Batch operation types

Type	Required fields	Description
'set'	path, id, data	Set a document (overwrites)
'update'	path, data	Update fields (path must include document ID)
'delete'	path	Delete a document

Transactions

Use transaction when you need to read and write atomically:

import { doc } from 'firebase/firestore';
import { getFirestoreContext } from 'svelte-firekit';

const db = getFirestoreContext();

await firekitMutations.transaction(async (tx) => {
  const ref = doc(db, 'counters/page-views');
  const snap = await tx.get(ref);
  const current = snap.data()?.count ?? 0;
  tx.update(ref, { count: current + 1 });
});