`edge.size()`

The size() method of the edge object measures the code of the playground: the source document, every o: export, the edge worker and the modules it imports. It measures the editor source (Local), the files a route serves right now (Deployed) or one saved version of a route (Archive), and resolves to a JSON report. It is the Code: Size… dialog (Alt+Shift+S) as an API.

Three related functions share the measurement: edge.size.text() returns an aligned text table, edge.size.local() a snapshot of the source without any network request, and edge.size.open() opens the dialog. Measuring code size shows the dialog.

Syntax

await edge.size()
await edge.size(options)

await edge.size.text()
await edge.size.text(options)

await edge.size.local()

await edge.size.open()
await edge.size.open(options)

Parameters

options Optional

An object with these properties:

mode Optional

A string. 'local' forces a Local measurement. Any other value, or none, measures the deployment when a route is available, and Local otherwise.

route Optional

A string: the route to measure. It must be one of Code.D. The default is Code.D[0].

version Optional

What to measure on that route:

'current': The live deployment. This is the default.
A non-negative integer n: The n-th newest saved version, among the newest 100: 0 is the newest.
A hexadecimal string: A SHA prefix of 1 to 40 characters, case-insensitive, that matches exactly one saved version. A string of digits such as '2' is a SHA prefix, not an index; pass the number 2 for an index.

Anything other than 'current' needs Deployed mode and a route.

refresh Optional

A boolean value: true bypasses the cached history and the archive snapshots.

signal Optional

An AbortSignal. Aborting it rejects the call with the signal's reason.

edge.size.text() accepts the same options plus its own, and edge.size.open() accepts mode, route, version, refresh and all. See Related functions. edge.size.local() takes none.

Return value

A Promise that resolves to a report. All sizes are raw byte counts. The top level of a report:

{
  mode,              // 'local' or 'deployed'
  basis,             // 'source', 'live' or 'archive'
  version,           // null, or { n, sha, date, editor, message, deleted, failed }
  complete,          // boolean
  issues,            // an array of strings
  routes,            // [] in Local, [route] otherwise
  deployed,          // a date string, '' or null
  message,           // the deploy note, '' in Local
  source,            // { bytes, lines, warning? }
  total,             // { local, deployed, wire, included, partial, files, ok, failed }
  exports,           // { local, deployed, wire, n }
  files,             // [ { path, type, local, deployed, wire, status, http? } ]
  composition,       // [ { type, bytes, share, estimated } ]
  compositionTotal,  // a number
  worker,            // null, or an object
  elapsed,           // seconds, with one decimal
  error              // only when the measurement failed
}

mode, basis

mode is 'local' or 'deployed'. basis says what was read: 'source' (the editor), 'live' (the current deployment) or 'archive' (a saved version).

version

null for Local and live reports. For an archive: { n, sha, date, editor, message, deleted, failed }. n is the index, or null for a full SHA that was seen earlier but is no longer among the newest 100; sha has 40 hexadecimal characters; message is the deploy note; failed marks a deployment attempt that failed.

complete, issues

complete is a boolean value that is false when parts of the measurement are missing. issues is an array of strings that say what is missing or went wrong; see Usage notes.

routes

[] in Local, and [route] in the other modes.

deployed

null in Local and for a failed archive attempt. For an archive, the date of the version. For a live report, the value of the deploy header of the root, or the date of the newest version, or '' if neither is known.

message

The deploy note of the deployment or version, and '' in Local.

source

{ bytes, lines, warning? }: the UTF-8 bytes and the lines of the source, with an optional warning string.

total

An object with these properties:

local: In Local, the source plus the worker bundle; otherwise the source alone.
deployed: The sum of the measured deployed bytes, or of the archived bytes that are known. null in Local.
wire: The bytes transferred, as the browser reports them. Only live reports have it.
included: The composition base: the root document plus the worker.
partial: true for an archive with missing bodies.
files: The number of files: / plus the exports.
ok, failed: How many files were measured and how many failed. null in Local.

exports

{ local, deployed, wire, n }: the same sums over the exports alone, and their number.

files

An array with the root / first and then the exports, the largest first. Each item is { path, type, local, deployed, wire, status, http? }.

type: A short content type: js, html, css, svg, json, wasm, txt, xml, bin, or the first four characters of another MIME subtype.
status: In Local, 'local'. For a live report, a glyph: ✓ for a file served byte for byte, ≠ for a file that differs, ~ for a file that cannot be compared byte for byte because it is re-serialized on deploy, such as the root document, and ✗ for a file that is not deployed or whose request failed. For an archive: 'archived', 'attempted' for a failed deployment attempt, or 'unavailable', which also sets the sizes to null.
http: The HTTP status, or 0, present only when the request was not OK.

composition, compositionTotal

composition is an array of { type, bytes, share, estimated }: one item per export type, plus markup (the rest of the root document) and worker (the bundle). share is a percentage with one decimal, and estimated marks a figure that is an estimate. For an archive, bytes and share are null for parts that are unknown. In live and archive reports the export bytes are scaled down when their sum exceeds the size of the root. compositionTotal is the base: the root plus the worker.

worker

null when the code has no worker. Otherwise an object that depends on the mode:

Local: { deployed: null, local, bundleGzip, exact, source, gzip, lines, modules, error?, importErrors? }. It counts every <script type=worker>.
Live: { deployed, exact, source, modules }, for edge workers only.
Archive: { deployed, bundleGzip, gzipCalculated: true, exact, source, gzip, lines, modules, missingModules, unavailableModules }.

exact says whether the worker size is exact or an estimate.

elapsed

The time the measurement took, in seconds with one decimal.

error Optional

A message, when the measurement failed.

Exceptions

The promise rejects with an Error that carries one of these messages.

Message	When
`A saved version requires Deployed mode.`	`version` was given with `mode: 'local'`.
`A saved version requires a deployment route.`	`version` was given and no route is available.
`Unknown deployment route: <route>`	`route` is not in `Code.D`.
`Unknown deployment version: <ref>`	No saved version matches `version`.
`Ambiguous deployment version: <ref>`	A SHA prefix matches more than one saved version.
`Deployment history: HTTP <status>`	The history could not be read, for example because you are signed out.
`Deployment history: unexpected HTML or redirected response`, `Invalid deployment history response`	The history answered with something that is not a list of versions.
`Archived <file>: HTTP <status>`, `Archived <file>: unexpected HTML or redirected response`	An archived file could not be read. A 404 is tolerated and becomes an entry in `issues`.

An aborted signal rejects with its reason.

Related functions

edge.size.text()

Resolves to a string: the same measurement as the aligned, box-drawing table that Copy as text produces. It takes the options of edge.size() and these:

units Optional: 'human', the default, splits each size into whole decimal units in aligned columns, such as 1MB 234kB 567B (1 kB is 1000 bytes). 'bytes' prints raw byte counts with , as the thousands separator.
order Optional: 'size', the default, lists files largest first. 'doc' keeps the document order.
cols Optional: A number: the width of the table in characters. The default is 132.
q Optional: A string: only files whose path contains it are listed.
off Optional: A Set of content types to leave out, such as new Set(['markup']). It must be a Set.

The table shows the source size and lines, the date and note of the deployment or version, the composition of the code by type with a stacked bar, the file table, the worker tables and worker:fs assets, a legend for the status glyphs and the time it took.

edge.size.local()

Resolves to a snapshot of what the editor source would deploy. It makes no request, resolves no import and builds no bundle.

{
  source:  { bytes, lines, edgeMarkers, parts: [ { type, bytes } ], warning? },
  files:   [ { path, type, mode, bytes } ],
  workers: [ { edge, bytes, lines, imports } ],
  fs:      [ { name, bytes } ],
  error?
}

files[0] is { path: '/', mode: 'root' }. The mode of an export is html, text, blob (an <img> with a data URL) or prop (o:content). edgeMarkers counts the edge:remove and edge:redact elements.

edge.size.open()

Opens the Code: Size dialog. It takes mode, route, version and refresh like edge.size(), and one more option:

all Optional: A boolean value: true opens the dialog in Deployed mode.

The dialog opens in Local mode unless all: true or a version is given, and it works without routes. The promise resolves, with no value, after the measurement has finished. Errors of the measurement are shown in the dialog and not thrown; the errors of Exceptions still reject.

Usage notes

Mode	`basis`	What is measured
Local	`'source'`	The editor source only. It extracts every `o:` export with the playground's own extractor and splits the source bytes by content type. It measures each `<script type=worker>` (bytes, gzip, lines, static imports) and each `worker:fs` asset, then builds the worker bundle with the playground's compiler, which may fetch imports, and measures every module that loaded. No route is needed.
Deployed	`'live'`	The files the route serves now. It requests `/` and every export from the route with `cache: 'no-store'` and `credentials: 'omit'`, three at a time.
Archive	`'archive'`	One saved version. It reads only the archived bodies of that version: the source, the root payload, the export payloads, the worker source and bundle, and the `worker:fs` assets. It never replaces the editor and never fills a gap from live files or imports.

Deployed measurements retry. Network errors, HTTP 5xx and 429 are retried in up to five more rounds, after 1, 2, 4, 8 and 16 seconds, one request at a time. A 404 or another status is final, and a file that still fails after the last round is reported as failed. Wire bytes come from Resource Timing. The static imports of workers are followed to a depth of 4, and at most 32 modules are fetched; the rest are reported as not fetched.
The requests are anonymous. They carry no cookies, so a file that the route does not serve to anonymous visitors is probably reported as ✗. A file that answers 200 without the deploy response header is also reported as not deployed.
worker.exact. The size of a live worker is an estimate when its exact bundle cannot be read. Local and archive reports use the bundle they have.
Archives need history. A saved version is read through the deployment history, which needs a signed-in account. The wire size of an archive is always null. Version numbers and SHA prefixes select from the newest 100 saved versions; a full SHA from outside them works if it was seen earlier in the tab. edge.versions() lists them.
Check before you trust a total. Look at complete, issues and total.partial. The issues of an archive can include Deployment artifact archive is unavailable., Archived source is unavailable., Archived root payload is unavailable., Archived worker main script is unavailable., Archived worker bundle unavailable., Separately deployed worker module bodies were not archived., Separately deployed worker WebAssembly bodies were not archived., Worker deployment failed for this version., This version deleted the deployment., Archived body unavailable: <path> and Some archived file bodies are unavailable.
The route is checked. Unlike edge.versions(), edge.size() accepts only a route from Code.D. With mode: 'deployed' and no route it measures Local without saying so.

Note: Measuring uses CompressionStream for gzip, Resource Timing and the Intl.NumberFormat units. See Browser support.

Examples

A Local report, as JSON and as text

Write each command to io.eval.js and read io.eval.json. Keep the semicolon before a line that starts with (, or the parenthesized object is parsed as a call of the line before.

const { total, exports, worker, complete } = await edge.size({ mode: 'local' });
({ total, exports, worker, complete })

await edge.size.text({ mode: 'local', units: 'bytes', order: 'doc', cols: 100, off: new Set(['markup']) })

Comparing the live deployment with the newest saved version

This needs a route in Code.D and, for the saved version, a signed-in account.

const live = await edge.size(), saved = await edge.size({ version: 0 });
({ live: live.total, saved: saved.total, issues: saved.issues })

A network-free snapshot, and the dialog on a saved version

await edge.size.local()
await edge.size.open({ mode: 'deployed', route: Code.D[0], version: 1 })  // the second-newest saved version

Specifications

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

Availability

Feature	Playground	RTEdge.net	Notes
`edge.size()`, Local	Yes	No	No route and no network. It may fetch the imports of a worker.
`edge.size()`, Deployed	Yes	No	Needs a route in `Code.D`.
`edge.size()`, Archive	Yes	No	Needs a route and a signed-in account.
`edge.size.text()`	Yes	No	Same requirements as the mode it measures.
`edge.size.local()`	Yes	No	Never makes a request.
`edge.size.open()`	Yes	No	The Code menu item is hidden in embedded playgrounds; the command, the shortcut and the call remain.