Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 11 additions & 7 deletions docs/explanation/content-addressed-schemas.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,27 +4,31 @@
the network. Python installs the same schemas from a wheel, one gzipped file per
version, where their size is nobody's problem.*

The raw epJSON schemas are about 10 MB each and there are 17 of them, roughly
11.9 MB gzipped for the set. On a page load that number decides your
The raw epJSON schemas are about 10 MB each and there are 18 of them, roughly
12.3 MB gzipped for the set. On a page load that number decides your
architecture, so the browser bundle stores the same information differently.

{{ parity("schema-access") }}

## Most of a schema is the previous schema

Object-type definitions barely change between EnergyPlus releases. `Zone` has
not changed since 8.9. Across the 18 versions the bundle indexes 14,092
type entries and finds only 2,568 distinct definitions behind them: 82% of what
not changed since 8.9. Across the 18 versions the bundle indexes 14,972
type entries and finds only 2,788 distinct definitions behind them: 81% of what
18 separate schemas would carry is a repeat of something already shipped.

So the bundle stores each unique definition once, keyed by a hash of its
content, and gives every version a manifest mapping type name to hash.

| | All 18 versions, gzipped |
| ---------------------------------------- | ------------------------ |
| Raw epJSON schemas, as Python ships them | 11,915 KB |
| Slimmed (documentation metadata dropped) | 2,922 KB |
| Content-addressed | about 1,000 KB |
| Raw epJSON schemas, as Python ships them | 12,277 KB |
| Slimmed (documentation metadata dropped) | 3,028 KB |
| Content-addressed | 1,189 KB |

The content-addressed figure is what a parse loads: the index, the 18 manifests
and the definitions. The prose pool, which only describing a type needs, adds
173 KB.

The two reductions are independent. Slimming keeps only what a parse needs and
discards the documentation weight, which otherwise sits on the critical path of
Expand Down
2 changes: 1 addition & 1 deletion docs/how-to/parse-in-the-browser.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Then point `httpSource` at it:
```

`httpSource` fetches the gzipped files and inflates them with
`DecompressionStream`, so the payload stays around 1 MB for all 18 versions. It
`DecompressionStream`, so the payload stays about 1.2 MB for all 18 versions. It
sniffs the gzip magic bytes first, so it works whether your host leaves
`Content-Encoding` unset or maps the `.gz` extension to
`Content-Encoding: gzip` (as Vite's dev server and nginx's `gzip_static` do),
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/slim-schema-format.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ flat `Record<typeName, hash>`. `types.json` is a flat `Record<hash, SlimType>`,
shared by every version.

Files are gzipped and inflated by the source. `httpSource` uses
`DecompressionStream` so the payload stays around 1 MB. It sniffs the gzip magic
`DecompressionStream` so the payload stays about 1.2 MB. It sniffs the gzip magic
bytes first, so it works whether the server leaves `Content-Encoding` unset or
sets it for the `.gz` extension, where the client inflates the body itself.

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/typescript/schemas.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ title: '@idfkit/schemas'
# `@idfkit/schemas`

EnergyPlus epJSON schemas for all 18 supported versions, content-addressed so
that the whole set is around 1 MB gzipped rather than 11.9 MB. See
that the whole set is about 1.2 MB gzipped rather than 12.3 MB. See
[Content-addressed schemas](../../explanation/content-addressed-schemas.md) for why,
and [Slim schema format](../slim-schema-format.md) for what a definition contains.

Expand Down
Loading