Sync and conflicts

fs keeps every file on this device and, once an account is connected, a second copy in the account. This page covers what that second copy asks of your app: the write and read rules, file states, adoption, conflicts, deletes, and picking up another device’s change.

The account is the FKN identity a person carries between sites, and that second copy is the account copy. The queue, adoption and conflicts belong to fs alone: opfs has no account half and cloud.fs has no local one, see storage.

The write rule

fs writes the account copy behind the OPFS copy and never waits for it, so the synchronous calls stay synchronous. OPFS is the browser’s own store for this origin, and the broker is the connection your app holds into FKN. When the in-memory layer flushes a write (see storage), fs writes OPFS, waits for it, then asks the broker whether an account is connected. The answer has three values:

Answer	What happens to the write
connected	fs writes the account copy in the background while the last account listing succeeded, and queues the path otherwise or when that write fails.
disconnected	Nothing is owed: no account was ever linked, the person signed out, or the token was refused.
unknown	Nobody could be asked, so fs queues the path and arms a retry.

Only disconnected drops work owed to the account, because treating unknown the same way would lose a write. A queued path waits for the drain, the background process that replicates queued writes and deletes to the account. Watch the rule run at the flush:

app.ts

import fs from '@fkn/lib/fs'
import { shell } from '@fkn/lib'

await fs.mount()
fs.writeFileSync('library/catalog.json', JSON.stringify({ items: [] }))
await fs.flush() // resolves once every dirty path was attempted, even when OPFS refused

shell.busyReasons() // without 'unsaved files' once OPFS took the bytes
fs.pending() // [], or ['library/catalog.json'] once a replicate failed or nobody could be asked

flush() resolved either way, so a refused OPFS write leaves the path dirty and only shell.busyReasons() shows it, see storage. A refused replicate is queued: fs warns with fs: cloud replicate failed, queued for adopt() and lists the path in pending().

The probe behind the answer waits 8 seconds for the broker, and 1 second while the last probe timed out. A timeout answers unknown, so a page whose broker never answers waits up to 8 seconds at its first mount() or flush.

Without OPFS there is nowhere to queue from. A write refuses with fs: cloud unreachable on unknown and with fs: no storage backend available on disconnected. The flush swallows that refusal and leaves the file dirty.

The read rule

fs reads OPFS first, asks the account only when OPFS has no such file, and caches an account hit into OPFS in the background. A local copy always wins, even when the account holds a newer one. Another device’s write stays invisible here until you ask for it:

app.ts

await fs.mount()
String(fs.readFileSync('library/catalog.json', 'utf8')) // this device's copy, whatever the account holds

await fs.flush() // nothing dirty, so the hydrate below may replace the entry
await fs.pull('library/catalog.json') // the account's copy, into OPFS and not into memory
await fs.remount() // hydrates again, OPFS first
String(fs.readFileSync('library/catalog.json', 'utf8')) // the account's bytes

The first read answered this device’s bytes and the last one the account’s. pull() reads the account, writes what it got into OPFS and resolves with it as a Blob, going around the in-memory layer, so the remount() follows. The flush() comes first because a hydrate leaves a dirty path alone (see storage), so over an unflushed write the pair would seem to do nothing.

pull() rejects with StorageNotFoundError when the account holds nothing at the path, which isNotFound(error) recognises. It rejects with StorageLockedError after a dismissed unlock card, see encryption. Guard the call: a new device often meets the first case.

Note

pull() and readFileSealed() take the path as written, with no normalisation, so pass the relative form you write with, see storage. The local half refuses a .. segment with opfs: invalid path.

Listings and pending work

A stamp is the updatedAt the account reported for a path. A file fs holds is in one of five states, and the state decides what the drain does with it next:

State	What a read sees	What a listing shows	What the drain does next
local only	this device’s bytes	the OPFS entry alone	nothing, until adopt() or the adopt card moves it
queued	this device’s bytes	one entry, the newer stamp	uploads it while the account stamp still matches
replicated	this device’s bytes	one entry, the newer stamp	nothing
conflicted	this device’s bytes	one entry, the newer stamp	asks your resolver or the conflict card
pending delete	ENOENT, until a remount() lists the account’s copy	the account’s entry, while it exists	retries it while the stamp still matches and the file was not recreated here, else abandons it

Under a connected account mount() lists both halves and merges them by path, and the newer updatedAt wins. Signed out or on unknown, the listing is the OPFS half alone. The stamps it saw are what conflict detection compares against. The merge decides an entry’s mtime and content type, never which bytes are loaded, so statSync can report the account’s newer time over this device’s older bytes.

replicating() answers whether the last listing was complete. It is true while signed out, when the account half was never asked, and false only after an account listing failed while connected, which suspends replication until a listing succeeds. pending() and pendingDeletes() list the paths still owed, so a status line reads the queue and not the flag:

app.ts

await fs.mount()

const status = () => {
  const queued = fs.pending().length + fs.pendingDeletes().length
  if (!fs.replicating()) return 'the account could not be listed, changes wait on this device'
  return queued > 0 ? `${queued} change(s) waiting to reach the account` : 'nothing waiting'
}

addEventListener('online', () => console.log(status())) // '1 change(s) waiting to reach the account', the drain starts too

shell.busyReasons() // includes 'storage replication' while a drain or an adopt offer is in flight

nothing waiting says the queue is empty and nothing about the account, since a signed-out app reads it too. For the account, ask account.info(). Queued work drains on its own: on online, on an account change and after every complete listing under an account.

A drain that threw or left per-file failures arms a retry, 60 seconds doubling up to 10 minutes. One that left a conflict unresolved arms nothing, so a timer never re-raises a dismissed card.

Note

A realm is one JavaScript execution context, a window or a worker. The queue lives in the origin’s localStorage, so a worker realm has none. A write still reaches the account from a relayed worker, but a replicate that failed or met unknown is never retried there. At most a console warning shows for it, see workers.

Adopting files written before sign-in

Files written before sign-in owe the account nothing and stay local. After a complete listing under an account with nothing queued, the broker offers the local-only files it has not been told to skip. The card is Add your files to your account?, with Add to my account and Keep local only.

fs remembers a decline per path in this origin’s localStorage and never asks about that path again. An account change runs the offer for the rest. The broker’s account menu still counts every local-only file, declined ones included, and can add them from there. Your app can ask the same question:

app.ts

const { paths, bytes } = await fs.adoptable() // ['library/catalog.json'] and its size, or [] and 0 without both halves

if (paths.length > 0 && confirm(`Add ${paths.length} file(s), ${bytes} bytes, to your account?`)) {
  const summary = await fs.adopt()
  summary.uploaded // ['library/catalog.json']
  summary.unresolved // [], once every conflict was settled
  for (const { path, error } of summary.failed) console.warn(path, error)
}

adoptable() counted one local-only file. The person agreed, and adopt() uploaded it. adopt() runs the drain’s own push with local-only files included, serialised so the two never race. Its summary has six lists: uploaded, kept (paths the account already held), resolved (each with its choice, 'local', 'cloud' or 'merged'), unresolved, deleted and failed (each with its error message).

adopt() rejects with fs: this needs a signed-in account on disconnected and fs: cloud unreachable on unknown, so connect the account first, see account and quota. A failed account listing aborts the run rather than guessing the account is empty. So does a locked account, which keeps the work queued, see encryption.

Conflicts

A conflict is a queued path whose account stamp moved since this device last saw it. Both sides changed, so pushing would overwrite the other device’s work. By default the broker shows its conflict card, Two versions of a file, with This device and Your account as the answers and a close that keeps both. Register a resolver with onConflict to decide in code instead:

app.ts

const off = fs.onConflict(async conflict => {
  if (!conflict.path.endsWith('.json')) {
    const localNewer = Date.parse(conflict.local.updatedAt ?? '') >= Date.parse(conflict.cloud.updatedAt ?? '')
    return localNewer ? conflict.readLocal() : conflict.readCloud() // one write, to the other side
  }
  const [local, cloud] = await Promise.all([conflict.readLocal(), conflict.readCloud()])
  try {
    const merged = { ...JSON.parse(await cloud.text()), ...JSON.parse(await local.text()) }
    return JSON.stringify(merged) // written to both sides, resolved as 'merged'
  } catch {
    return null // both copies stay, reported under unresolved
  }
})

off() // back to the conflict card

The resolver merges a JSON file, keeps the newer side of any other file, and leaves a side that does not parse for later. It receives one FileConflict, whose readLocal() and readCloud() answer each side’s bytes as a Blob, read once and remembered. It returns a ConflictResolution from @fkn/lib/fs: the write data that wins, or null, see TypeScript.

fs recognises the very Blob from readLocal() or readCloud() by identity, so picking a side costs one write. Any other value is a merge that fs writes to both sides, a rebuilt Blob with equal bytes included. null leaves both copies and reports the path under unresolved. A resolver that throws counts as null.

Comparing updatedAt stamps, as the example does, is a heuristic and never proof of which copy is newest, see reading with the seal time.

Deletes

A delete removes the OPFS copy and, while connected, the account copy. fs queues a refused account delete and warns with fs: cloud delete failed, queued for retry. On unknown, fs queues the delete only for a path the account was seen to hold. A delete always drops a queued upload of the same path, so a file deleted locally owes the account nothing:

app.ts

await fs.mount()
fs.unlinkSync('library/catalog.json')
await fs.flush() // the OPFS delete now, and the account delete too while the account is connected

fs.pendingDeletes() // [], or ['library/catalog.json'] once the account delete failed or could not be attempted

Under a connected account both deletes ran inside the flush, so the queue holds the path only after a refusal or an unknown. The drain retries it under the rule in the state table.

Deletes do not travel between devices: another device that still holds the file lists it again, and there are no tombstones, see limitations.

Reading with the seal time

readFileSealed(path) reads a file and reports when the copy was sealed, as { data, sealedAt }. On fs it follows the read rule. A local hit answers sealedAt: null, because an OPFS file carries no envelope, so the stamp arrives only for a path this device does not hold. On cloud.fs it always reads the account, which is the form a high-water mark wants:

app.ts

const { data, sealedAt } = await cloud.fs.readFileSealed('backup/library.bin') // the account's copy and its seal time
const newestSeen = localStorage.getItem('backup:sealedAt')

if (sealedAt !== null && (newestSeen === null || sealedAt > newestSeen)) {
  localStorage.setItem('backup:sealedAt', sealedAt)
  apply(data) // newer than any copy this device applied
}

apply ran only when the stamp beat the newest this device had applied. sealedAt is the writer’s own claim about when it sealed, not proof of being newest. An older but authentic copy is still authentic, and the mark is what stops it from replacing a newer one.

The stamp is an ISO string authenticated with the bytes, so it describes exactly those bytes. It is null for an object sealed before the seal time existed, a broker too old to report it, or a stamp no Date can express.

Both reads reject the way pull() does. On fs the call goes around the in-memory layer, so it does not see an unflushed synchronous write, and it never caches what it fetched into OPFS.

What follows the account

A file follows the account to every device that signs in. A delete does not.

The first listing after a sign-out wipes the stamps this device remembered, so one account’s stamps never vouch for the next account’s files. Signing out leaves OPFS untouched, so the next account on the same browser sees the previous account’s local files and may be offered them. It also leaves the pending queue in place, because only a local delete drops a queued upload. A write queued under one account therefore drains into the next account, or conflicts with it.

Errors you might see

The four rows these calls meet most, each linked to the catalogue:

Message	What happened
Concurrent update, retry	Another writer moved the object between the presign and the commit, or between the read and the delete, so the service, the FKN server keeping account files, refused. The path is queued, and adopt() lists it under failed.
fs: cloud unreachable	The probe answered unknown to adopt(), or to a write or delete with no OPFS to queue from. Retry once the broker answers.
fs: no storage backend available	A write or delete with no OPFS met a definite sign-out.
fs: this needs a signed-in account	adopt() ran while signed out. Connect the account first, see account and quota.

Every other message has its row on every error. The exact shapes of AdoptSummary, FileConflict, ConflictResolution and SealedRead are in the generated reference for fs.

See also

• storage
• encryption
• account and quota
• every error
• limits and timeouts