`edge.versions()`

The versions() method of the edge object lists the saved versions of a deployed route: one entry for each deployment that the history recorded, newest first. Its sub-function edge.versions.load() writes one of them into the agent folder as a file, so that you can read it or diff it with your own tools.

Every deploy is recorded as a version, together with its optional note from edge.save.limit({ message }). The same history feeds the versions viewer (the ?? URL suffix), Smart Undo and edge.size({ version }).

Syntax

await edge.versions()
await edge.versions(options)

await edge.versions.load(ref)
await edge.versions.load(ref, options)

Parameters

options Optional

An object with this property:

route Optional: A string: the route whose history to read. The default is Code.D[0]. It is not checked against Code.D, and it is used as written, so pass the route the way Code.D holds it: my-site, my-site/docs or example.com. A longer spelling such as my-site.rt.ht probably finds nothing.

ref (for load() only)

Which version to write:

A number: The version with that n: 0 is the newest.
A string: A SHA prefix. It selects the first, that is the newest, version whose full SHA starts with it. The comparison is case-sensitive and does not check for ambiguity. A string of digits such as '2' is a SHA prefix, not an index, and '' matches the newest version.

Return value

edge.versions() returns a Promise that resolves to an array of objects, newest first, with at most 100 entries:

[
  { n: 0, sha: 'a1b2c3d', date: '2026-10-04T12:00:00.000Z', editor: '', message: 'Hero: tighter spacing', deleted: false },
  …
]

n: A number: the position in the list. 0 is the newest version.
sha: A string: the first 7 hexadecimal characters of the version's identifier.
date: A string: an ISO date. It is the date of the history entry, which is written a little after the deploy returns, so it is slightly later than the time of the deploy.
editor: A string: the lowercased email address of the editor who saved the version, when an editor saved it and you are the owner. Otherwise ''.
message: A string: the 💬 deploy note, or '' when there was none. For older entries without the usual prefix, the first line of their message.
deleted: A boolean value: true for an entry that records a deletion. The list stops at the newest deletion, so in practice every entry has deleted: false.

edge.versions.load() returns a Promise that resolves to an object:

file: A string: the name of the file it wrote, 🕐.<n>.<sha7>.html.
n, sha, date, message: As above, for the version it wrote.
ok: A boolean value: false when the saved version could not be decoded into source. The file then holds the raw saved text, or is empty when the version could not be fetched, instead of HTML.

Exceptions

Rejection	When
`Error('Unauthenticated.')`	You are not signed in.
`Error` with the server's message, or `'Unable to load deployment history.'`	The history did not answer with a list.
`TypeError`	`Code.D` is empty and no `route` was given. Pass `route` or set `Code.D`.
`Error('Agent Folder Share is not active.')`	`load()` without an active share.
`Error('No version <ref> — edge.versions() lists <count>.')`	`load()` found no version for `ref`.

Usage notes

Who sees which versions. The history needs a signed-in account. It lists the versions you committed as the owner of the route, which include the saves of your editors, and the versions you saved as an editor, so an editor sees only their own saves. It reads the newest 100 and stops at the newest deletion: that entry and everything older are left out, so a route that was deleted and deployed again starts a fresh list.
Wait a few seconds after a deploy. The entry is written in the background after edge.save.limit() resolves. A list taken in that gap misses the new version, and the stale list stays cached until the next deploy or a reload.
Results are cached per route for the lifetime of the tab. The cache is dropped after a deploy or a delete of that route from this tab or from another tab of the same browser. A deploy made somewhere else shows up after a reload.
Refer to a version by its sha. n is relative to the list at the time of the call: after new deploys the same version has a higher n.
The two SHA rules differ. edge.versions.load() takes the first case-sensitive match. edge.size({ version }) needs a prefix that matches exactly one version, case-insensitively, and reports Ambiguous deployment version otherwise.

`edge.versions.load()`

load() needs an active Agent Folder Share, which works in Chrome and Edge on desktop. It downloads the saved state of that version, decodes its source and writes it into the root of the work folder as 🕐.<n>.<sha7>.html, overwriting a file with the same name. The file has the same shape as 📄.html.

Loading never touches the editor, the output or the undo state.
The files are plain files. Nothing deletes them, and File Sync does not manage them. See Agent files.
Read, search or diff the files with your own tools, for example against 📄.html. Do not return version contents through eval results: they are large.

Examples

Listing the three newest versions

Write this to io.eval.js and read io.eval.json. It needs a signed-in account and a route in Code.D.

(await edge.versions()).slice(0, 3)

Writing a version to disk and diffing it

await edge.versions.load(1)   // { file: '🕐.1.a1b2c3d.html', n: 1, sha: 'a1b2c3d', date, message, ok: true }

Then compare it with the current source in the shared folder:

plain

diff 🕐.1.*.html 📄.html

Reading the history of another route

await edge.versions({ route: 'my-site/docs' })

Specifications

Not part of any specification. edge.versions() is an RTCode.io playground function.

Availability

Feature	Playground	RTEdge.net	Notes
`edge.versions()`	Yes	No	Needs a signed-in account and a route.
`edge.versions.load()`	Yes	No	Also needs Agent Folder Share: Chrome or Edge on desktop, in a top-level playground.