Documentation Upgrades

[runspired]

Notes for the release

• adds an overview to the api docs website
• updates our long-since outdated README
• adds documentation for debugging
• ensures all our npm package repository links take you directly to the correct package and have a meaningful description

[github-actions]

Asset Size Report for 1ea2607

Modern Builds

☑️ EmberData has not changed in size

If any packages had changed sizes they would be listed here.

Changeset

Full Asset Analysis (Modern)

Asset Size Report
=================


Library: EmberData
┌────────────┬─────────────┐
│  (index)   │   Values    │
├────────────┼─────────────┤
│   bytes    │ '166.81 KB' │
│ compressed │ '34.95 KB'  │
│  packages  │      8      │
│  modules   │     44      │
└────────────┴─────────────┘

Package: @ember-data/model
┌──────────────┬────────────┐
│   (index)    │   Values   │
├──────────────┼────────────┤
│    bytes     │ '45.76 KB' │
│  compressed  │ '9.59 KB'  │
│ % Of Library │   '27.4'   │
└──────────────┴────────────┘
	Module                                            | Bytes     | Compressed | % of Package  | % Of Library
	-----------------------------------------------------------------------------------------------------
	@ember-data/model/-private                        | 45.29 KB  | 9.49 KB    | 99.0          | 27.1
	@ember-data/model/index                           | 486.00 B  | 101.81 B   | 1.0           | 0.3

Package: @ember-data/store
┌──────────────┬────────────┐
│   (index)    │   Values   │
├──────────────┼────────────┤
│    bytes     │ '42.43 KB' │
│  compressed  │ '8.89 KB'  │
│ % Of Library │   '25.4'   │
└──────────────┴────────────┘
	Module                                            | Bytes     | Compressed | % of Package  | % Of Library
	-----------------------------------------------------------------------------------------------------
	@ember-data/store/-private                        | 41.43 KB  | 8.68 KB    | 97.6          | 24.8
	@ember-data/store/index                           | 1022.00 B | 214.10 B   | 2.4           | 0.6

Package: @ember-data/record-data
┌──────────────┬────────────┐
│   (index)    │   Values   │
├──────────────┼────────────┤
│    bytes     │ '24.18 KB' │
│  compressed  │ '5.06 KB'  │
│ % Of Library │   '14.5'   │
└──────────────┴────────────┘
	Module                                            | Bytes     | Compressed | % of Package  | % Of Library
	-----------------------------------------------------------------------------------------------------
	@ember-data/record-data/-private                  | 24.18 KB  | 5.06 KB    | 100.0         | 14.5

Package: @ember-data/serializer
┌──────────────┬────────────┐
│   (index)    │   Values   │
├──────────────┼────────────┤
│    bytes     │ '20.42 KB' │
│  compressed  │ '4.28 KB'  │
│ % Of Library │   '12.2'   │
└──────────────┴────────────┘
	Module                                            | Bytes     | Compressed | % of Package  | % Of Library
	-----------------------------------------------------------------------------------------------------
	@ember-data/serializer/json                       | 7.36 KB   | 1.54 KB    | 36.0          | 4.4
	@ember-data/serializer/-private                   | 5.60 KB   | 1.17 KB    | 27.4          | 3.4
	@ember-data/serializer/json-api                   | 3.79 KB   | 813.03 B   | 18.6          | 2.3
	@ember-data/serializer/rest                       | 2.87 KB   | 614.64 B   | 14.0          | 1.7
	@ember-data/serializer/index                      | 611.00 B  | 127.99 B   | 2.9           | 0.4
	@ember-data/serializer/transform                  | 215.00 B  | 45.04 B    | 1.0           | 0.1

Package: @ember-data/adapter
┌──────────────┬────────────┐
│   (index)    │   Values   │
├──────────────┼────────────┤
│    bytes     │ '15.93 KB' │
│  compressed  │ '3.34 KB'  │
│ % Of Library │   '9.6'    │
└──────────────┴────────────┘
	Module                                            | Bytes     | Compressed | % of Package  | % Of Library
	-----------------------------------------------------------------------------------------------------
	@ember-data/adapter/rest                          | 7.88 KB   | 1.65 KB    | 49.5          | 4.7
	@ember-data/adapter/-private                      | 3.79 KB   | 811.99 B   | 23.8          | 2.3
	@ember-data/adapter/error                         | 1.82 KB   | 390.91 B   | 11.4          | 1.1
	@ember-data/adapter/index                         | 1.41 KB   | 302.92 B   | 8.9           | 0.8
	@ember-data/adapter/json-api                      | 1.03 KB   | 221.85 B   | 6.5           | 0.6

Package: ember-data
┌──────────────┬───────────┐
│   (index)    │  Values   │
├──────────────┼───────────┤
│    bytes     │ '8.66 KB' │
│  compressed  │ '1.81 KB' │
│ % Of Library │   '5.2'   │
└──────────────┴───────────┘
	Module                                            | Bytes     | Compressed | % of Package  | % Of Library
	-----------------------------------------------------------------------------------------------------
	ember-data/index                                  | 2.11 KB   | 452.29 B   | 24.4          | 1.3
	ember-data/-private                               | 1.75 KB   | 374.77 B   | 20.2          | 1.0
	ember-data/adapters/errors                        | 1.19 KB   | 254.95 B   | 13.7          | 0.7
	ember-data/setup-container                        | 368.00 B  | 77.09 B    | 4.2           | 0.2
	ember-data/relationships                          | 318.00 B  | 66.61 B    | 3.6           | 0.2
	ember-data/serializers/embedded-records-mixin     | 274.00 B  | 57.40 B    | 3.1           | 0.2
	ember-data/serializers/json-api                   | 251.00 B  | 52.58 B    | 2.8           | 0.1
	ember-data/adapters/json-api                      | 245.00 B  | 51.32 B    | 2.8           | 0.1
	ember-data/serializers/json                       | 243.00 B  | 50.90 B    | 2.7           | 0.1
	ember-data/serializers/rest                       | 243.00 B  | 50.90 B    | 2.7           | 0.1
	ember-data/transform                              | 241.00 B  | 50.48 B    | 2.7           | 0.1
	ember-data/adapters/rest                          | 237.00 B  | 49.64 B    | 2.7           | 0.1
	ember-data/serializer                             | 232.00 B  | 48.60 B    | 2.6           | 0.1
	ember-data/adapter                                | 226.00 B  | 47.34 B    | 2.5           | 0.1
	ember-data/model                                  | 222.00 B  | 46.50 B    | 2.5           | 0.1
	ember-data/store                                  | 222.00 B  | 46.50 B    | 2.5           | 0.1
	ember-data/attr                                   | 218.00 B  | 45.66 B    | 2.5           | 0.1
	ember-data/version                                | 161.00 B  | 33.72 B    | 1.8           | 0.1

Package: ember-inflector
┌──────────────┬───────────┐
│   (index)    │  Values   │
├──────────────┼───────────┤
│    bytes     │ '6.67 KB' │
│  compressed  │ '1.40 KB' │
│ % Of Library │   '4.0'   │
└──────────────┴───────────┘
	Module                                            | Bytes     | Compressed | % of Package  | % Of Library
	-----------------------------------------------------------------------------------------------------
	ember-inflector/lib/system/inflector              | 2.96 KB   | 635.59 B   | 44.4          | 1.8
	ember-inflector/lib/system/inflections            | 1.59 KB   | 340.84 B   | 23.8          | 1.0
	ember-inflector/lib/system                        | 471.00 B  | 98.67 B    | 6.9           | 0.3
	ember-inflector/index                             | 379.00 B  | 79.39 B    | 5.6           | 0.2
	ember-inflector/lib/helpers/pluralize             | 369.00 B  | 77.30 B    | 5.4           | 0.2
	ember-inflector/lib/utils/make-helper             | 332.00 B  | 69.55 B    | 4.9           | 0.2
	ember-inflector/lib/system/string                 | 318.00 B  | 66.61 B    | 4.7           | 0.2
	ember-inflector/lib/helpers/singularize           | 296.00 B  | 62.00 B    | 4.3           | 0.2

Package: @ember-data/debug
┌──────────────┬────────────┐
│   (index)    │   Values   │
├──────────────┼────────────┤
│    bytes     │ '2.77 KB'  │
│  compressed  │ '593.49 B' │
│ % Of Library │   '1.7'    │
└──────────────┴────────────┘
	Module                                            | Bytes     | Compressed | % of Package  | % Of Library
	-----------------------------------------------------------------------------------------------------
	@ember-data/debug/index                           | 2.27 KB   | 487.69 B   | 82.2          | 1.4
	@ember-data/debug/setup                           | 505.00 B  | 105.79 B   | 17.8          | 0.3

Modern Builds (No Rollup)

☑️ EmberData has not changed in size

If any packages had changed sizes they would be listed here.

Changeset

Full Asset Analysis (Modern)

Asset Size Report
=================


Library: EmberData
┌────────────┬──────────┐
│  (index)   │  Values  │
├────────────┼──────────┤
│   bytes    │ '0.00 B' │
│ compressed │ '1.00 B' │
│  packages  │    0     │
│  modules   │    0     │
└────────────┴──────────┘

[github-actions]

Performance Report for 1ea2607

Scenario - basic-record-materialization: ⚠️ Performance regressed

⚠️ duration
phase estimated regression +59ms [10ms to 117ms] OR +1.58% [0.27% to 3.13%]
☑️ Phase [navigationStart] => [start-data-generation]
phase no difference [-3ms to 3ms]
☑️ Phase [start-data-generation] => [start-push-payload]
phase no difference [-2ms to 1ms]
☑️ Phase [start-push-payload] => [start-peek-records]
phase no difference [-12ms to 24ms]
☑️ Phase [start-peek-records] => [start-record-materialization]
phase no difference [-2ms to 1ms]
☑️ Phase [start-record-materialization] => [end-record-materialization]
phase no difference [-4ms to 45ms]
☑️ Phase [end-record-materialization] => [Test End]
phase no difference [-1ms to 25ms]

Scenario - relationship-materialization-simple: ☑️ Performance is stable

☑️ duration
phase no difference [-15ms to 3ms]
☑️ Phase [navigationStart] => [start-find-all]
phase no difference [-4ms to 2ms]
☑️ Phase [start-find-all] => [start-materialization]
phase no difference [-5ms to 3ms]
✅ Phase [start-materialization] => [end-materialization]
phase estimated improvement -3ms [-6ms to -1ms] OR -1.05% [-1.97% to -0.18%]
☑️ Phase [end-materialization] => [Test End]
phase no difference [0ms to 0ms]

Scenario - relationship-materialization-complex: ☑️ Performance is stable

☑️ duration
phase no difference [-43ms to 8ms]
☑️ Phase [navigationStart] => [start-data-generation]
phase no difference [-3ms to 2ms]
☑️ Phase [start-data-generation] => [start-push-payload]
phase no difference [-1ms to 0ms]
☑️ Phase [start-push-payload] => [start-peek-records]
phase no difference [-4ms to 9ms]
☑️ Phase [start-peek-records] => [start-record-materialization]
phase no difference [0ms to 1ms]
⚠️ Phase [start-record-materialization] => [start-relationship-materialization]
phase estimated regression +5ms [1ms to 9ms] OR +1.19% [0.24% to 2.18%]
☑️ Phase [start-relationship-materialization] => [end-relationship-materialization]
phase no difference [-33ms to 1ms]
✅ Phase [end-relationship-materialization] => [Test End]
phase estimated improvement -5ms [-9ms to -1ms] OR -1.05% [-1.97% to -0.19%]

Scenario - unload: ☑️ Performance is stable

☑️ duration
phase no difference [-19ms to 1ms]
☑️ Phase [navigationStart] => [start-push-payload]
phase no difference [-5ms to 2ms]
☑️ Phase [start-push-payload] => [start-unload-records]
phase no difference [-7ms to 2ms]
☑️ Phase [start-unload-records] => [end-unload-records]
phase no difference [-5ms to 1ms]
☑️ Phase [end-unload-records] => [Test End]
phase no difference [0ms to 0ms]

Scenario - unload-all: ⚠️ Performance regressed

⚠️ duration
phase estimated regression +159ms [57ms to 254ms] OR +1.05% [0.38% to 1.67%]
☑️ Phase [navigationStart] => [start-push-payload]
phase no difference [-5ms to 2ms]
☑️ Phase [start-push-payload] => [start-materialization]
phase no difference [-11ms to 10ms]
☑️ Phase [start-materialization] => [start-unload-all]
phase no difference [-5ms to 7ms]
⚠️ Phase [start-unload-all] => [end-unload-all]
phase estimated regression +156ms [57ms to 259ms] OR +1.21% [0.44% to 2.01%]
☑️ Phase [end-unload-all] => [Test End]
phase no difference [0ms to 0ms]

Scenario - destroy: ☑️ Performance is stable

☑️ duration
phase no difference [-7ms to 11ms]
☑️ Phase [navigationStart] => [start-push-payload]
phase no difference [-4ms to 3ms]
☑️ Phase [start-push-payload] => [start-destroy-records]
phase no difference [-3ms to 5ms]
☑️ Phase [start-destroy-records] => [end-destroy-records]
phase no difference [-2ms to 1ms]
☑️ Phase [end-destroy-records] => [Test End]
phase no difference [0ms to 0ms]

Scenario - add-children: ☑️ Performance is stable

☑️ duration
phase no difference [-10ms to 4ms]
☑️ Phase [navigationStart] => [start-push-initial-payload]
phase no difference [-4ms to 4ms]
✅ Phase [start-push-initial-payload] => [start-push-update-payload]
phase estimated improvement -2ms [-4ms to 0ms] OR -0.94% [-1.95% to -0.01%]
☑️ Phase [start-push-update-payload] => [end-push-update-payload]
phase no difference [-3ms to 1ms]
☑️ Phase [end-push-update-payload] => [Test End]
phase no difference [0ms to 0ms]

Scenario - unused-relationships: ☑️ Performance is stable

☑️ duration
phase no difference [-4ms to 11ms]
☑️ Phase [navigationStart] => [start-push-payload]
phase no difference [-1ms to 5ms]
☑️ Phase [start-push-payload] => [end-push-payload]
phase no difference [-4ms to 4ms]
☑️ Phase [end-push-payload] => [Test End]
phase no difference [0ms to 0ms]

[jenweber]

I think having the package breakdown is a huge benefit! For the intro sections, I think it would benefit from a catchy hook, if you have one. “What makes this special?” is the question to try and answer. Also, as it is currently, it requires a lot of implicit knowledge to understand what the library does for you. What do you think about saying some of it in plainer terms? I can help draft some possible changes if you are into the idea. I also think this can be merged as is and provide a lot of valuable info.

Also would you like to standardize around referring to the whole thing as EmberData? We can update that in lots of other places if you want.