Tracking: typed access through collections, from a second pass building an example app #405

A second pass building a small app against @haverstack/core, after #360 landed, found it a clear improvement: type handles (#373) removed hand-written content interfaces and every cast, and typos, out-of-enum values and null on required fields became compile errors.

What's left is mostly about how far the typing reaches, and nearly all of it traces back to one choice: typing was added as handle-first overloads on StackClient. So typing reaches only the verbs that got an overload, query filters and migrations stay untyped, every compile mistake is a long TS2769, each typed operation picks its own scope, and one record an older app can't read blanks a whole typed list. Rather than patch each of those separately, this epic makes the handle the receiver: client.collection(Book) returns a collection whose every verb is typed, and which reports the records it can't type instead of throwing on them.

Each sub-issue carries its own problem, decision, reasoning and action list. This issue records the order.

Decisions that span issues

• Collections are typed by content (Collection<ContentOf<S>>), not by schema, and their outer types never flatten their parameter, so an app that names its content with an interface sees that name in hovers. (Typed access through collections, with records that don't fit reported rather than thrown #409)
• A collection write outside the handle's family is refused as not found, through an internal expectation Stack checks against the read it already makes. There is no public ifBaseId. (Stack checks a typed collection's write expectation #408)
• A patch to a record stored at an older version commits the migration as its own write first, when the caller may migrate. (Typed access through collections, with records that don't fit reported rather than thrown #409)
• Records the handle can't type are misfits, reported beside a query's records, carried on subscription changes, and thrown as MisfitError (outside the StackError hierarchy, since it has no wire representation) from get(). (Typed access through collections, with records that don't fit reported rather than thrown #409)
• Handles carry name and migratesFrom and stay plain data; migrations are typed values passed to Stack.open(), and registerMigration() goes. (Handles carry their lineage; typed migrations are passed at open #407)

Order

Order is by dependency first, then to minimise churn: changes that rewrite many tests go early, so later issues write their tests against the final API, and the README goes last so it's written once.

1. Validation errors name what was validated #406 Validation errors name what was validated. Independent of everything; first because it changes expected messages in tests across core.
2. Handles carry their lineage; typed migrations are passed at open #407 Handles carry their lineage; typed migrations are passed at open. Rewrites every typeHandle() call and every test that registers a migration. Also changes @haverstack/commons.
3. Stack checks a typed collection's write expectation #408 Stack checks a typed collection's write expectation. Internal only; can run in parallel with Handles carry their lineage; typed migrations are passed at open #407.
4. Typed access through collections, with records that don't fit reported rather than thrown #409 Typed access through collections, with misfits reported (blocked by Handles carry their lineage; typed migrations are passed at open #407 and Stack checks a typed collection's write expectation #408). The largest issue.
5. Collection filters and sorts are checked against the content type #410 Collection filters and sorts are checked against the content type (blocked by Typed access through collections, with records that don't fit reported rather than thrown #409).
6. String enums can be declared open #411 String enums can be declared open (blocked by Typed access through collections, with records that don't fit reported rather than thrown #409; can run in parallel with Collection filters and sorts are checked against the content type #410).
7. Rewrite "Writing an app" for collections, typed migrations and app installs #412 Rewrite "Writing an app" for collections, typed migrations and app installs (last).

With more than one person: #406, #407 and #408 can all run at once; #409 waits for #407 and #408; #410 and #411 can run in parallel after #409; #412 goes last.

Related

• Typed access through collections, with records that don't fit reported rather than thrown #409 also fixes a bug in today's typed subscribe(): under ScopedStack it types a tombstone's content: {} as the handle's content. It has no separate issue because Typed access through collections, with records that don't fit reported rather than thrown #409 deletes the code it lives in. If it's needed sooner, the standalone fix is to skip narrowing when the change's record has deletedAt set.