UCD.js Docs

Lockfile

Architecture notes for @ucdjs/lockfile

@ucdjs/lockfile owns the persistent metadata format for mirrored UCD stores.

Role

  • Validates .ucd-store.lock and per-version snapshot.json files.
  • Encodes the contract between ucd-store, writable backends, and store-serving apps.
  • Separates metadata integrity checks from the higher-level store lifecycle.

Public Package Docs

User-facing overview of lockfile helpers and snapshot parsing.

UCD Store

See where lockfile reads, writes, and conflict resolution happen.

FS Backend

Lockfile persistence depends on backend `write` and `mkdir` support.

Store App

The hosted store app serves lockfile and snapshot data over HTTP.

Mental Model

The package has two data shapes:

  • lockfile: store-level metadata for resolved versions and filters
  • snapshot: version-level file manifest with hashes and sizes

And two usage modes:

  • strict parsing APIs that throw typed errors
  • permissive OrUndefined APIs for best-effort reads

Method Flows

readLockfile()

LockfileSchemaparseLockfileFromContent()FileSystemBackendreadLockfile()LockfileSchemaparseLockfileFromContent()FileSystemBackendreadLockfile()alt[invalid JSON or schema][valid]alt[fs read fails][empty file][content present]CallerreadLockfile(fs, ".ucd-store.lock")read(lockfilePath)errorLockfileInvalidError(lockfile could not be read)""LockfileInvalidError(lockfile is empty)raw JSON stringparse raw contentsafeParse(json)validation errorLockfileInvalidErrorthrowlockfile dataLockfileCaller

writeLockfile()

FileSystemBackendcanUseLockfile()writeLockfile()FileSystemBackendcanUseLockfile()writeLockfile()alt[directory missing]alt[backend is read-only][writable backend]CallerwriteLockfile(fs, path, data)fs.features has write + mkdir?falseno-optrueexists(dirname(path))mkdir(dirname(path))write(path, JSON.stringify(data, null, 2))successCaller

Snapshot lifecycle

SnapshotSchemaFileSystemBackendgetSnapshotPath()readSnapshot()/writeSnapshot()SnapshotSchemaFileSystemBackendgetSnapshotPath()readSnapshot()/writeSnapshot()alt[read][write]CallerreadSnapshot(fs, version)getSnapshotPath(version)read(version/snapshot.json)raw contentparse + validateSnapshot or LockfileInvalidErrorwriteSnapshot(fs, version, snapshot)getSnapshotPath(version)ensure directory existswrite(snapshot.json)success or no-op on read-only backendCaller

Design Notes

  • canUseLockfile() is a capability check, not a backend-type check.
  • Invalid content is normalized into LockfileInvalidError so higher-level code can present consistent errors.
  • Parsing helpers exist both for filesystem-backed reads and raw string content from HTTP or memory.
  • Snapshot paths are version-derived, which keeps store metadata deterministic.

Testing Use

  • strict vs permissive parse helpers
  • invalid JSON and invalid schema branches
  • write skipping on read-only backends
  • directory creation on first write
  • parity between raw-content parse helpers and filesystem-backed reads

FS Backend

Architecture notes for @ucdjs/fs-backend

Path Utils

Architecture notes for @ucdjs/path-utils

On this page

RoleRelated DocsMental ModelMethod FlowsreadLockfile()writeLockfile()Snapshot lifecycleDesign NotesTesting Use