tree2: Cleanup creation of field schema

[CraigMacomber]

Description

Adopts a new pattern for documenting workarounds for microsoft/TypeScript#55758, making the documentation more centralized, and more clear about what the desired extends clauses are.

Also avoids using the constructor for FieldSchema and instead use static builders whose type parameters can be constrained.

This, when combined with const generic type parameters removes the reason for existence of the generic FieldSchema builders on SchemaBuilder, so those have been removed (the ones which depend on specific field kinds are kept).

Also adds some runtime validation in FieldSchema for cases the type system can't fully handle.

Breaking Changes

Users of SchemaBuilder.field (or new FieldSchema) and SchmeaBuilder.fieldRecursive should use FieldSchema.create and FieldSchema.createUnsafe.

Reviewer Guidance

The review process is outlined on this wiki page.

[noencke]

Looks good. I have one question. You changed many of places where AllowedTypes are passed in to be arrays rather than single elements. Is that a convention that you are favoring? Or is it now mandatory? I don't see where it would have changed to be mandatory, but I wanted to ask.

[msfluid-bot]

⯅ @fluid-example/bundle-size-tests: +890 Bytes

Metric Name	Baseline Size	Compare Size	Size Diff
aqueduct.js	445.38 KB	445.38 KB	■ No change
connectionState.js	680 Bytes	680 Bytes	■ No change
containerRuntime.js	238.52 KB	238.52 KB	■ No change
loader.js	148.11 KB	148.11 KB	■ No change
map.js	48.08 KB	48.08 KB	■ No change
matrix.js	141.86 KB	141.86 KB	■ No change
odspDriver.js	90.1 KB	90.1 KB	■ No change
odspPrefetchSnapshot.js	41.77 KB	41.77 KB	■ No change
sharedString.js	162.74 KB	162.74 KB	■ No change
sharedTree2.js	263.3 KB	264.17 KB	⯅ +890 Bytes
Total Size	1.69 MB	1.69 MB	⯅ +890 Bytes

---

Baseline commit: 96d9e2a

Generated by 🚫 dangerJS against cbc9f19

[CraigMacomber]

Looks good. I have one question. You changed many of places where AllowedTypes are passed in to be arrays rather than single elements. Is that a convention that you are favoring? Or is it now mandatory? I don't see where it would have changed to be mandatory, but I wanted to ask.

FieldSchema works in terms of AllowedTypes, which is always an array. The places that were converted to call its create functions which didn't explicitly use arrays were using variadic functions, which was a workaround for us not having a version of typescript with https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html#const-type-parameters . This patterns is bad, mainly because it makes the almost never intended case of passing an empty array look like the default behavior.

Note that none of these are the preferred customer facing API which is in our internal spec, which all are on SchemaaBuilder and take ImpliedAllowedTypes, which accepts both array and single argument forms, but will not (and cannot) tolerate recursive types. Thus I expect the only real use in app code these APIs will be FieldSchema.createUnsafe as part of recursive types.