DEV Community: Rafael Soares

React Native Widgets Without Duplicating Business Logic in Swift

Rafael Soares — Fri, 16 Oct 2026 14:00:00 +0000

"Next service" is a short label with a surprisingly long list of dependencies.

In OdoKeep, it can depend on the vehicle, its recorded maintenance, the distance unit, the user's snooze decisions, and the current service forecast. Monthly spend has another set of rules, including converting a record at its own date when it was paid in a different currency.

Those answers already existed in TypeScript. Adding iOS widgets would have been a good opportunity to copy them into Swift and spend the next year fixing disagreements between the two versions.

Instead, the app writes the answers down.

OdoKeep is built with React Native and Expo. It has four WidgetKit widgets: vehicle details, deadlines, monthly spend, and servicing. The widget extension is a separate process. It does not run React Native or open the app's MMKV store.

The boundary between the two processes is a JSON snapshot in an App Group container. The TypeScript app builds it from the same modules used by the dashboard. Swift decodes it and draws the result.

Share finished answers across the process boundary

The snapshot is a presentation contract, rather than an export of raw records. Amounts are formatted, units are applied, service labels are translated, and deep links are already built. Even the spend-chart buckets carry their finished labels and normalized bar ratios.

The following excerpt shows the kind of shape the contract uses:

interface WidgetSpendBucket {
  id: string;
  label: string;
  ratio: number;
  isCurrent: boolean;
}

interface WidgetDeadline {
  id: string;
  label: string;
  vehicleId: string;
  vehicleName: string;
  dueDate: string;
  dueDateLabel: string;
  warningFrom: string;
  url: string;
}

There is still useful structure in the file. Swift needs identities to support vehicle selection, dates to advance the display, and ratios to render bars. What it does not need is a second implementation of the garage's financial or maintenance rules.

The dashboard's attention list, service forecast, and spend calculations feed lib/widgets/snapshot.ts. plugins/widgets/WidgetsSnapshot.swift mirrors the decoder contract. When a field changes meaning, the shared snapshot version changes too. A decoder that does not understand that version falls back to asking the user to open the app.

That is a much easier failure to investigate than a widget confidently showing the wrong interpretation of a new field.

Let the calendar advance without the app

The calendar is the deliberate exception to precomputed answers. A widget can remain visible while the app is unopened for days. A deadline that says "in three days" has to change after midnight without asking React Native to rebuild it.

The snapshot therefore stores a deadline as a local calendar day and a warningFrom day. It also stores translated countdown strings keyed by day offset:

"0"  -> Today
"1"  -> Tomorrow
"2"  -> In 2 days
"-2" -> 2 days overdue

The real table is produced through the app's translation function and extends sixty days into the past and 120 into the future, with an overdue fallback. Swift counts calendar days and looks up the corresponding finished string. It can advance the state at the precomputed warning date without learning how the app decided that date.

For services measured in distance, the snapshot carries a fixed label instead. Waiting overnight does not add kilometers to an odometer.

WidgetTimeline.swift builds an entry for now and one per local midnight for the next week, with an .atEnd refresh policy. The snapshot stays the same while the entry date changes. This supplies future display states to WidgetKit; it does not promise that an extension runs at an exact wall-clock instant. WidgetKit controls its refresh schedule, as Apple's documentation on keeping widgets up to date explains.

Replace the snapshot before requesting a reload

Choosing when to write the file is another part of the design. The main write happens as the app leaves the foreground, close to the moment the user returns to the home screen. A four-second timer after mount supplies an initial snapshot for a session that has not backgrounded yet. Observable preference and configuration changes re-arm that timer.

The record repository does not expose a subscription for every record write, so a record added after the timer fires reaches the snapshot on the next background transition. That is the freshness boundary. A widget also cannot learn about a shared vehicle edit that the app has not yet pulled.

The writer uses synchronous file operations on that lifecycle path. It writes the entire JSON document under a scratch name, then moves it over the real snapshot with overwrite enabled. This keeps the normal decoder path away from a half-written document. The scratch file is removed before reuse if an earlier attempt was interrupted.

Only after replacement does the small Expo native module request a WidgetKit timeline reload. Writing bytes alone would leave the existing timeline in place until the system requested another one. Reloading is a request to the scheduler, so freshness still depends on iOS and a successful snapshot write.

Privacy belongs in the snapshot builder

The data allowed across the boundary is narrower than the data available in the app. When the biometric lock is enabled, the widget snapshot contains no odometer or money values. Those fields are null; the sensitive values are not serialized and then hidden in the view. The license plate is never included, regardless of lock state. Deadlines and service information remain available.

The Swift views also mark sensitive values for system privacy redaction. That supports iOS's display controls, while the builder controls which values reach the extension at all.

Sign-out and account deletion remove the widget snapshot and request a reload. Deleting the file is part of ending the session, not just a side effect of unmounting the hook that writes it. Otherwise, a saved snapshot could outlive the account that produced it.

Reuse the boundary for Siri and Shortcuts

The same architectural choice supports Siri and Shortcuts. Their read intents use a separate presentation snapshot stored in the app's Documents directory. Those intents compile into the app target; they are not the WidgetKit extension. The builders share inputs, but the files and consumers have distinct contracts.

A write shortcut opens a deep link into an existing app form. It does not update storage from Swift. The route still applies the share role, plan limits, odometer checks, and sync behavior that apply when the user opens that form normally. Siri parameters prefill a request; they do not bypass the app's write path.

Keep the extension reproducible with Expo prebuild

The native build is reproducible too. This project regenerates its ignored iOS directory through Expo prebuild. A target added by hand in Xcode would not survive clean generation, so plugins/with-widgets.js creates and configures the extension, links the Swift files and resources, declares the App Group, and describes the second target to EAS for signing. This follows Expo's config plugin model for changes that must survive native regeneration.

One build setting in that plugin deserves a mention: ENABLE_DEBUG_DYLIB = NO for the extension. The implementation records a failure where App Intents metadata extraction inspected the debug stub's dependencies, did not find AppIntents, and skipped extraction without failing the build. Configurable widgets then had no usable intent and displayed an empty state despite the signed-in app. The setting makes the debug extension use the binary layout expected by that metadata path.

The tests check the pure snapshot builder, the Swift decoder's required fields, deep links, localization tables, shared colors, fonts, and native configuration. These are targeted contract checks, not a generated cross-language schema or a replacement for running the extension on a device. They catch several ways two separately compiled consumers can drift before that drift reaches the home screen.

This is the boundary I would reuse for another React Native product: let the app own the meaning of its data, and send the extension a bounded, versioned description of what it can display. Leave enough date structure for the display to age, and make the age of every other answer an explicit consequence of the last write.

These four widgets are implemented in OdoKeep for iOS. If you track a vehicle, they are a compact way to see its deadlines and next service without opening the full logbook.

Replacing Geospatial Database Reads with Static JSON Tiles and Cloudflare

Rafael Soares — Fri, 09 Oct 2026 14:00:00 +0000

Every OdoKeep user looking for nearby fuel prices was asking a different question against the same data.

The location changed. The radius changed. The selected fuel changed. The underlying station list was shared by everyone and rebuilt on a daily schedule.

That was enough to reconsider where the query happened.

OdoKeep is a React Native vehicle logbook. Its fuel-price feature consumes national feeds from Portugal, Spain, France, Italy, and Austria. The tile module documents a working set of roughly 46,000 stations; the count changes with the feeds. Originally, the app asked the backend for nearby stations and country-level brand counts.

The current price-serving path reads JSON files from Cloudflare R2 through a public custom domain. Supabase still handles the private garage data. The publishing job also reads source attribution metadata and reports its health. What went away was the need for the database to answer each phone's fuel-price lookup.

I could have published one country file and let the app filter it. That would be easy to build, but a nearby lookup should not require downloading a country's entire station list. The shared dataset needed a partition that matched the way people use the screen.

One grid module for the publisher and the phone

The partition is a half-degree grid. lib/fuel-prices/tiles.ts contains the grid arithmetic used by both the publisher and the client:

const TILE_DEGREES = 0.5;

function tileKey(lat: number, lon: number): string {
  return `${Math.floor(lat / TILE_DEGREES)}_${Math.floor(lon / TILE_DEGREES)}`;
}

Lisbon at 38.72, -9.14 lands in 77_-19. The negative coordinate makes Math.floor significant: truncation would put points west of Greenwich in the wrong cell.

The published layout is small enough to describe without an API specification:

fuel/
  index.json
  sources.json
  brands/
    PT.json
    ES.json
    ...
  tiles/
    77_-19.json
    77_-18.json
    ...

A tile contains station facts: coordinates, identity, address information, prices, opening hours when supplied, and source update times. It does not contain distance from the user. Distance belongs to a lookup, not to a station.

Fetch a bounding box, then filter by distance

For a search, the client first computes the cells covering the circle's bounding box. The approximate latitude span comes from the radius divided by kilometers per degree. The longitude span is widened by the cosine of latitude, because longitude degrees become narrower farther north.

Fetching a bounding box is intentionally a little imprecise. A corner tile can be requested even if none of its stations fall inside the circle. After loading, the app uses haversine distance to discard stations outside the requested radius and sort the rest. It keeps the same Earth radius as the query this replaced.

The file count is where the grid size earns its place. A half-degree cell is roughly 56 km tall, with a narrower width at the latitudes served. The default 10 km radius means a 20 km diameter. The tests sample the documented coverage region and assert at most four cells for that default and at most nine for the 30 km radius ceiling.

The diameter is easy to forget when estimating this. A statement such as "a 30 km search fits in a 56 km cell" sounds reasonable until you draw the circle.

A coarser grid would reduce the maximum number of requests but enlarge the files needed for the common search. The chosen grid spends more requests on a large radius so that a small radius can use smaller pieces.

The index makes the empty parts cheap. It lists only cells with stations and carries the grid size and build timestamp. A coastal search can eliminate known empty cells before requesting them. The client rejects an index built on a different grid rather than using keys with the wrong meaning.

Brand counts are also built once per country. Changing the brand filter no longer requires a country-wide aggregation in the database.

Once those files are loaded, changing fuel, brand, or radius can reuse the held stations. The network no longer has to participate in every adjustment to the view.

Empty and failed are different outcomes

The actual tile cache trusts entries for six hours. It holds parsed data in memory, persists copies for later launches, and keeps one in-flight promise per key. Two consumers asking for a tile simultaneously share the request. When a usable old copy exists and the network fails, that copy can still serve the lookup.

The most important cache change was giving tile retrieval three outcomes:

type TileOutcome =
  | { status: "ok"; stations: TileStation[] }
  | { status: "empty" }
  | { status: "failed" };

An empty cell and a cell I could not fetch are different evidence.

Suppose a lookup crosses two populated cells. One returns normally and the other returns a 503 with no usable cached copy. Combining the first cell's stations into a result would silently shrink the searched area. That shorter list could then be sorted and cached as if it answered the whole question.

stationsAround returns failure when any required tile fails. The higher layer can fall back to its previous search cache or explain that it could not retrieve the data. It does not turn a missing piece of the map into a newly complete result.

The current handling of a 404 is more limited: it is treated as an empty outcome and remembered for five minutes. That short lifetime matters during publication, when a cell can be temporarily unavailable. The index avoids many such requests, but a 404 still does not give the same certainty as a versioned, internally consistent dataset.

Publish complete datasets, tiles before index

Publication has a corresponding completeness rule. The TypeScript builder requires every configured country and refuses to publish when any adapter fails. Otherwise, an upstream outage in one country would become a new station set in which that country had disappeared. Keeping the previous full build is preferable to publishing that omission as fresh data.

The scheduled GitHub Action runs the builder with Bun. The sync path uses built-in modules and project source files, so this job does not install the mobile app's dependency tree. Its output is a directory; uploading it is a separate workflow step.

The JSON files are gzipped before upload and served with the appropriate content encoding. gzip -n leaves the timestamp out of the compressed header, so identical input does not acquire different bytes merely because it was compressed on another day. The objects carry a one-hour public cache directive.

Tiles are uploaded before the index. Publishing the index first would advertise new keys that a failed upload might never deliver.

This ordering does not make the deployment atomic. Files are replaced in place, and a client can see a mixture of builds. Pruning can also remove an old tile while a client still holds an earlier index. For current fuel-price browsing, the implementation accepts that limited consistency and uses short-lived missing-tile handling. A dataset requiring a consistent snapshot would need generation-specific paths and a pointer switched only after all files were available.

Where this architecture fits

R2 is useful here because its published pricing has no internet egress bandwidth charge. Storage and operations are still part of the R2 pricing model, and cache configuration still matters. A public custom domain can use Cloudflare caching, as described in the public bucket documentation. I do not have a before-and-after bill to attach to this article; the concrete change is that price lookups no longer consume database reads or database egress.

Daily publication also does not make every station's price current to the minute. The source update time is retained separately, and attribution travels with the dataset. The national feeds have different update behavior and reuse conditions. Serving a file rather than a row does not change either.

This approach fits because the dataset is public, shared, geographically bounded, and updated much less often than it is read. I would make a different choice for private data, per-user authorization, or live prices whose freshness depended on each transaction.

For this feature, the phone already knew the location, radius, and filters. Giving it a reusable local slice let it finish the query without repeatedly asking the server to rediscover the same stations.

You can see the resulting fuel-price browser in OdoKeep, alongside the vehicle logbook it supports. The iOS app is available if you want to try it around your own route.

Offline Receipt OCR in Expo: The Hard Part Starts After Text Recognition

Rafael Soares — Fri, 02 Oct 2026 14:00:00 +0000

On a fuel receipt, 1,899 might be a unit price. 95 might be a product grade. 04 might be a pump number. The OCR engine can read all three perfectly and still leave me with the wrong fuel record.

I added receipt scanning to OdoKeep, my vehicle logbook built with React Native and Expo. Recognition runs on the phone: Apple's Vision framework on iOS and bundled Google ML Kit text recognizers on Android. The photograph and recognized text are not uploaded by this feature.

The native module handles acquisition, image preparation, text recognition, and the temporary photograph. Interpreting the result lives in TypeScript under lib/receipt-scan. Keeping that boundary lets the parser run in ordinary unit tests, independent of a camera or a particular phone.

Keep the evidence attached to the text

The native result is richer than a string. It contains lines, source boxes, available confidence information, and, where the recognizer exposes them, alternative transcriptions. The parser uses those positions to connect a field back to the place it came from on the photograph.

The pipeline is roughly:

Photograph
  -> native OCR lines and boxes
  -> numeric tokens with units and source positions
  -> ranked field candidates
  -> arithmetic corroboration
  -> reviewed draft
  -> original fuel or charging form

There is no write between text recognition and the original form. A scan produces a prefill the user can correct and save through the same route they already use for manual entry.

Rank readings before choosing a number

Numeric normalization is the first place where the text stops being simple. Receipts can use decimal commas, decimal points, grouping spaces, Swiss apostrophes, or native digit sets. Thermal printing can also lose a separator or turn a digit into a letter.

The tokenizer can retain more than one plausible reading of a number. A token such as 1,899 does not have to be resolved before the parser has seen its label, unit, and neighbors. A possible repair has a lower standing than an ordinary reading, and its source location stays attached to it.

Candidate ranking starts with printed evidence. An explicit quantity unit is strong evidence for quantity. A rate such as EUR/L is strong evidence for unit price. A total label is evidence for the reference amount.

Dates, percentages, distance readings, and administrative labels are excluded from the amount slots. An unlabelled number does not become a missing quantity because it happens to make the calculation convenient. The search keeps at most twenty candidates per slot, which bounds the combinations it considers.

Multiplication is corroboration

The arithmetic seems like the easy part:

quantity * unitPrice = printedTotal

It is useful, but it needs a smaller claim than "the receipt is correct". A matching product corroborates a candidate reading. It does not prove that the image was read correctly or that all three fields describe the transaction I think they describe.

The parser compares the product with half a currency minor unit, plus floating point slack. For a currency with two decimal places, the base tolerance is half a cent. It does not allow a percentage of the bill, which would make larger receipts accept larger OCR errors.

This example is used in the tests:

31.93 L x 1.899 EUR/L
TOTAL 60.84 EUR

The product is approximately 60.635. A loose percentage tolerance could accept 60.84. The currency-based comparison rejects that arithmetic match.

Another test has a perfectly readable quantity and price, a subtotal that matches their product, and a lower final paid amount:

40 L x 1.80 EUR/L
Subtotal 72 EUR
Discount 4 EUR
Total 68 EUR

The parser retains 68 as the printed total reference. It does not promote 72 to the final total just because 72 makes the multiplication work. Quantity and unit price can still be useful even when the final amount includes a discount.

OdoKeep calculates the saved cost from quantity multiplied by unit price, minus an optional reviewed discount. The printed total is not copied into the saved cost. It also cannot supply a missing quantity or a missing unit price through division.

If only the total was recognized, the user still needs to enter the amounts. If quantity was recognized and price was not, the prefill leaves price empty. A partial result is allowed to remain partial.

For scans that do not pass the arithmetic check, the app can request another reading with higher contrast. The two passes are compared by arithmetic corroboration and then by the amount fields they recovered. A tie keeps the original pass. Date, time, station, and other non-amount fields can fill gaps from the losing pass because both readings refer to the same photograph.

Even that better reading goes through review. More evidence changes the ranking; it does not remove the user's opportunity to correct it.

Units and currencies need explicit choices

Units create their own class of believable errors. Liters, US gallons, imperial gallons, kilograms, cubic meters, and kilowatt-hours are all valid in the app's fuel or charging domain. They are not interchangeable.

A receipt that prints only gal cannot settle which gallon it means. The importer asks the user. If a compatible liquid unit is converted, quantity is multiplied by the volume factor and unit price is divided by the same factor:

convertedQuantity = printedQuantity * factor
convertedUnitPrice = printedUnitPrice / factor

This preserves their product before input rounding. The importer rounds converted inputs to at most three decimal places, so the original form's recalculated cost can differ slightly from the printed reference. Keeping the printed unit avoids that conversion rounding.

Physical dimension conflicts are handled more cautiously. A quantity printed in liters and a price explicitly printed per kilowatt-hour cannot be combined into a fuel cost. The parser retains the quantity and its unit and leaves price empty. It does not reinterpret one dimension as another.

Currency is equally explicit. If the receipt names a different currency, the user can keep it. If they choose the configured currency instead, the importer keeps quantity and clears unit price. No exchange rate is assumed during that choice. Displaying a saved foreign-currency cost later is a separate responsibility of the app's dated conversion layer.

Regional context comes from the device region independently of the interface language. Someone using an English interface in Portugal should not have every receipt interpreted as American. Explicit currency codes and units carry stronger evidence than regional defaults.

Recognition and photograph lifecycle

On iOS, Vision uses accurate recognition with language correction disabled. That is a deliberate setting for this input: numeric quantities and abbreviated product lines do not benefit from every assumption that helps a language model repair prose. Supported language hints are checked against the configured Vision request before being supplied.

On Android, the app bundles the Latin, Chinese, Devanagari, Japanese, and Korean text recognizers described in the ML Kit text recognition documentation. Bundling increases binary size and makes those recognizers available offline. The document-scanner acquisition path has separate Google Play services requirements and may need an initial download; the picker and bundled OCR provide a fallback. This does not establish support for every writing system.

Image handling matters just as much as field ranking. Orientation is normalized into the pixels, and the retained OCR boxes must agree with the displayed photograph. Both native implementations can try rotations when the initial reading is sparse, but a few extra fragments are not enough to justify turning the image.

Temporary copies belong to a scan session. A cancelled session cannot write a late photograph after cleanup, and one review cannot remove another review's image. A draft also belongs to the form that requested it and can be consumed once. Returning to that form again must not overwrite the user's corrections with the old scan.

Test interpretation separately from recognition

The parser tests include two real receipt transcriptions and synthetic cases for regional formats, ambiguous units, discounts, bad dates, alternate readings, and partial handoff. Those tests check what the parser does with OCR text. They are not a measured recognition rate on an image corpus. Low light, faded print, and script coverage still need device-level evaluation.

That separation makes failures easier to investigate. If the characters are wrong, I look at acquisition and recognition. If the characters are right but the record is wrong, I look at the parser's evidence and the handoff. A complete-looking JSON object would hide the difference.

Receipt scanning is part of OdoKeep. If you keep fuel or charging records, you can try the workflow in the iOS app: photograph the receipt, inspect what was recovered, and finish in the ordinary form.

Keeping Offline Edits Safe in React Native with MMKV and Supabase

Rafael Soares — Fri, 25 Sep 2026 14:00:00 +0000

A record that comes back after you delete it is a good way to make someone stop trusting a logbook.

That was one of the failure cases I had to address in OdoKeep, my vehicle tracking app. A user could create a record, delete it while the insert was still traveling, and see it again on the next sync. The local delete worked. The server insert worked. The queue's explanation of what had happened was wrong.

OdoKeep uses React Native and Expo, MMKV for local persistence, and Supabase for the server copy. The repositories write locally and enqueue the operation. Screens can use the local data while the sync manager deals with the network.

That makes saving a fill-up possible without a connection. It also means the queue has to describe more than a list of requests to try later.

A queued create is different from a traveling create

The first useful distinction was between an operation that had not been sent and one that had been sent but had not returned.

Consider an ordinary offline session:

Create record locally
Queue INSERT
Delete record locally
Cancel queued INSERT

There is no reason to contact the server. The record never existed there. Folding the create and delete into nothing is the correct optimization.

Now put a slow connection between the second and third steps:

Create record locally
Send INSERT
Delete record locally
Cancel queued INSERT
Server finishes INSERT
Next pull returns the record

Removing an operation from an array cannot recall a request already on the wire. The queue still called the create "pending", and the delete treated that word as proof that the server had never seen it.

The fix is a set of operation IDs currently in flight. In lib/sync-queue.ts, the part of coalescing that looks for a cancellable create now includes this condition:

const pendingCreate = pending.find(
  (op) => op.type === "create" && !this.inFlight.has(op.id),
);

If that create has already been sent, deleting the record must enqueue a server delete. It can no longer cancel the pair locally.

The set is deliberately held in memory. After a restart, the process has no live request to track. Persisting an inFlight flag would leave the next launch believing that an operation was still being sent, with nothing left to clear it. The durable queue survives; the description of this process's active requests does not.

This set also keeps an operation out of a second flush while the first request is outstanding. A sync triggered by reconnecting and another triggered by a refresh gesture must not send the same insert concurrently. The manager holds a guard around the flush, and the queue independently excludes in-flight operations from its due list. Even a user request that skips backoff still respects that exclusion.

Recovering an insert when the response disappears

There is another awkward case after an insert: the server may commit the row and the phone may lose the response.

On the next attempt, a plain insert can fail because the ID already exists. Treating that as a permanent rejection would roll back a local record that the server had successfully saved.

For the ordinary create path, the sync manager asks PostgREST to ignore a duplicate ID rather than overwrite it. If that produces no returned row, it reads the ID back. A readable row is confirmation that the create landed, and the device adopts it. If that confirmation request fails, the operation stays retryable. An unreadable collision is not accepted as success.

This is not an exactly-once delivery system. It is a retry path that can recover evidence of an insert without replacing an existing row's contents.

Updating the version you actually edited

Sharing a vehicle introduced a different problem. Two people can edit a record based on the same server version, while one or both are offline.

An update filtered only by ID gives the last sync permission to erase the earlier writer's changes. Both requests can succeed. Neither person learns that their edit lost.

Queued updates therefore carry baseUpdatedAt: the server timestamp the device knew before the local edit. The essential write condition looks like this, simplified from lib/sync-manager.ts:

const write = client
  .from(tableName)
  .update(operation.data)
  .eq("id", operation.data.id);

if (operation.baseUpdatedAt) {
  write.eq("updated_at", operation.baseUpdatedAt);
}

const result = await write.select(returningColumns);

The update can land only while the row still has the version it was edited against. The Supabase update API supports returning the affected rows through .select(), which makes an empty match observable to the client.

Capturing the base is easy to get subtly wrong. After the first local edit, the device's row may contain a locally generated timestamp. A second edit must not replace the queued operation's base with that value. The server has never issued it. Coalescing keeps the original server base and merges the payload changes.

A newly created row is another exception. Until the server confirms the create, its local timestamp cannot serve as a server precondition. The queue distinguishes "a create is still recorded" from "a create is still cancellable" for exactly this reason.

An empty update result also needs interpretation. It might mean another writer changed the row. It might mean the row was deleted. On a shared vehicle, it might mean the user's access was revoked or their role changed.

The conflict branch checks whether a readable row exists with a newer server timestamp. Only that evidence produces the stale-write message. The operation goes through the permanent refusal path, the user is told, and the device reconciles with the server. Retrying the rejected payload without the original precondition would recreate the overwrite this check was introduced to prevent.

The current policy is straightforward: the server copy wins a confirmed conflict. There is no field-level merge or conflict editor. An operation from an older build that has no base also cannot receive this protection retroactively. Those are useful limits to state when describing what the system guarantees.

Pull with a server watermark

The pull side needs the same care about timestamps. A phone can be two minutes fast. If it saves its own current time as the delta watermark, it asks the next pull to skip changes through a point in the server's future.

lib/delta-watermark.ts advances the watermark from the timestamps in returned rows instead. An empty response retains the previous watermark. The selected server timestamp is kept in its original string form for the next exclusive comparison, rather than being reformatted through the phone's date serializer.

The phone's clock is useful for retry delays. It cannot certify which server changes the phone has observed.

Retry budgets and regression tests

Failures also have to preserve the difference between "no" and "not now". The queue records total failed attempts separately from failures that count toward its retry limit. Transport failures and known temporary server failures drive capped exponential backoff without spending the permanent failure allowance. A brief service interruption should not remove a locally created vehicle and all the records queued against it.

The regression tests exercise these decisions directly: cancelling an unsent create, keeping a delete after an in-flight create, withholding work from a second flush, recovering a lost insert response, preserving an update's original base, and distinguishing a conflict from missing access. The server and storage are mocked in these tests. They verify the client's decisions, not the deployed policies or a real mobile network.

None of these fixes changed the fuel form. They changed the evidence the sync layer requires before it calls a write cancelled, confirmed, or permanently refused.

If you are building an offline queue, the create-then-delete test is worth adding early. Hold the insert response open, delete the local row, and inspect what remains queued. It exposes an assumption that an ordinary airplane-mode test never reaches.

I build OdoKeep for people who want to keep their vehicle history without making connectivity a requirement for every entry. These are some of the less visible decisions behind that promise. The app is available on the App Store.