Simpler card model (#34)

* newlines for doc comments

* drop primitives

* revise attraction lights

* drop EnumLike fields

* reduce constants

* revise card model

* fix legalities entry

* revise doc

* revise doc

* cleanup: rm primitives.ts

* finish merging in root types for single/double sided split cards

* restore AnyMultiFaced

* update doc

* revise group definitions

* further revise groups

* revise doc

* use a link here too

* improve card doc

* trim whitespace

Author: scarletcs

src/internal/Primitives.ts

@@ -3,24 +3,27 @@ import { ScryfallLayout, ScryfallLayoutGroup } from "./values";
 import { ScryfallCardFace } from "./CardFace";
 import { ScryfallCardFields } from "./CardFields";
 
-type Layout<T extends ScryfallLayout> = Pick<ScryfallCardFields.Core.All, "layout"> & {
-  layout: T | `${T}`;
+type Layout<T extends `${ScryfallLayout}`> = Pick<ScryfallCardFields.Core.All, "layout"> & {
+  layout: `${T}`;
 };
 
 /**
  * A collection of types representing Scryfall cards of each possible layout.
  *
- *
- * An individual type exists for each possible layout: {@link ScryfallCard.Normal}, {@link ScryfallCard.Transform}, etc.
- *
- * Then various groups exist to help describe cards of indeterminate layout:
- * - {@link ScryfallCard.Any} describes any card at all. Think of it as like `any` but for cards.
+ * This collection is focused around four core varieties of cards:
  * - {@link ScryfallCard.AnySingleFaced} describes any card with one face and no `card_faces` property, e.g. {@link ScryfallCard.Normal Normal} or {@link ScryfallCard.Saga Saga}.
- * - {@link ScryfallCard.AnyMultiFaced} describes any card with multiple faces. It may be a split card with both "faces" on the front, or a double-sided card with faces on the front and back of the card. It also collects the next two groups on this list.
  * - {@link ScryfallCard.AnySingleSidedSplit} describes any card with multiple faces where both faces are on the front, e.g. {@link ScryfallCard.Adventure Adventure}, {@link ScryfallCard.Flip Flip}, or {@link ScryfallCard.Split Split}.
  * - {@link ScryfallCard.AnyDoubleSidedSplit} describes any card with multiple faces where the faces are on the front and back of the card, e.g.  {@link ScryfallCard.Transform Transform},  {@link ScryfallCard.ModalDfc ModalDfc}, or  {@link ScryfallCard.ReversibleCard ReversibleCard}.
+ * - {@link ScryfallCard.ReversibleCard} describes solely reversible cards.
+ *
+ * It also provides broader groupings:
+ * - {@link ScryfallCard.Any} describes any card at all. Think of it as like `any` but for cards.
+ * - {@link ScryfallCard.AnySplit} is an alias for either AnySingleSidedSplit or AnyDoubleSidedSplit.
+ * - {@link ScryfallCard.AnyMultiFaced} is an alias for AnySingleSidedSplit, AnyDoubleSidedSplit, or Reversible. This describes all layouts that can have a `card_faces` field.
  *
- * We recommend starting from `ScryfallCard.Any` to describe generic API responses, and you will need to do type narrowing to access more specific fields.
+ * There is also an alias for each possible layout: {@link ScryfallCard.Normal}, {@link ScryfallCard.Transform}, etc.
+ *
+ * We recommend starting from {@link ScryfallCard.Any} to describe generic API responses, and you will need to do type narrowing to access more specific fields.
  *
  * @example // Type narrowing by layout
  * const mysteryCard: ScryfallCard.Any = getCard();
@@ -45,9 +48,16 @@ type Layout<T extends ScryfallLayout> = Pick<ScryfallCardFields.Core.All, "layou
 export namespace ScryfallCard {
   /** The abstract root implementation of cards. */
   export type AbstractCard = ScryfallObject.Object<ScryfallObject.ObjectType.Card> & ScryfallCardFields.Core.All;
+}
 
-  type SingleFace = AbstractCard &
-    Layout<ScryfallLayoutGroup.SingleFaceType> &
+export namespace ScryfallCard {
+  /**
+   * Any card with a single-faced layout.
+   *
+   * Examples: {@link ScryfallLayout.Normal}, {@link ScryfallLayout.Mutate}, {@link ScryfallLayout.Token}.
+   */
+  export type AnySingleFaced = AbstractCard &
+    Layout<ScryfallLayoutGroup.SingleFacedType> &
     ScryfallCardFields.Gameplay.RootProperties &
     ScryfallCardFields.Gameplay.CardSpecific &
     ScryfallCardFields.Gameplay.CardFaceSpecific &
@@ -58,95 +68,108 @@ export namespace ScryfallCard {
     ScryfallCardFields.Print.CardSideSpecific &
     ScryfallCardFields.Print.CardFaceSpecific;
 
-  type MultiFace<T extends ScryfallCardFace.AbstractCardFace> = AbstractCard &
-    Layout<ScryfallLayoutGroup.MultiFaceType> &
-    ScryfallCardFields.Gameplay.RootProperties &
-    ScryfallCardFields.Gameplay.CardSpecific &
-    ScryfallCardFields.Gameplay.CardFaces<T> &
-    ScryfallCardFields.Print.RootProperties &
-    ScryfallCardFields.Print.CardSpecific;
-
-  type SingleSidedSplit = MultiFace<ScryfallCardFace.Split> &
-    Layout<ScryfallLayoutGroup.SingleSidedSplitType> &
-    ScryfallCardFields.Gameplay.CardSideSpecific &
-    ScryfallCardFields.Print.CardSideSpecific &
-    ScryfallCardFields.Print.SingleSideOnly;
-
-  type DoubleSidedSplit = MultiFace<ScryfallCardFace.DoubleSided> & Layout<ScryfallLayoutGroup.DoubleSidedSplitType>;
-
-  type AlwaysOversized = {
-    oversized: true;
-  };
-
   /** A card with the Normal layout. */
-  export type Normal = Layout<ScryfallLayout.Normal> & SingleFace;
+  export type Normal = AnySingleFaced & Layout<ScryfallLayout.Normal>;
 
   /** A card with the Meld layout. */
-  export type Meld = Layout<ScryfallLayout.Meld> & SingleFace;
+  export type Meld = AnySingleFaced & Layout<ScryfallLayout.Meld>;
 
   /** A card with the Leveler layout. */
-  export type Leveler = Layout<ScryfallLayout.Leveler> & SingleFace;
+  export type Leveler = AnySingleFaced & Layout<ScryfallLayout.Leveler>;
 
   /** A card with the Class layout. */
-  export type Class = Layout<ScryfallLayout.Class> & SingleFace;
+  export type Class = AnySingleFaced & Layout<ScryfallLayout.Class>;
 
   /** A card with the Saga layout. */
-  export type Saga = Layout<ScryfallLayout.Saga> & SingleFace;
+  export type Saga = AnySingleFaced & Layout<ScryfallLayout.Saga>;
 
   /** A card with the Mutate layout. */
-  export type Mutate = Layout<ScryfallLayout.Mutate> & SingleFace;
+  export type Mutate = AnySingleFaced & Layout<ScryfallLayout.Mutate>;
 
   /** A card with the Prototype layout. */
-  export type Prototype = Layout<ScryfallLayout.Prototype> & SingleFace;
+  export type Prototype = AnySingleFaced & Layout<ScryfallLayout.Prototype>;
 
   /** A card with the Battle layout. */
-  export type Battle = Layout<ScryfallLayout.Battle> & SingleFace;
+  export type Battle = AnySingleFaced & Layout<ScryfallLayout.Battle>;
 
   /** A card with the Planar layout. */
-  export type Planar = Layout<ScryfallLayout.Planar> & SingleFace & AlwaysOversized;
+  export type Planar = AnySingleFaced & Layout<ScryfallLayout.Planar>;
 
   /** A card with the Scheme layout. */
-  export type Scheme = Layout<ScryfallLayout.Scheme> & SingleFace & AlwaysOversized;
+  export type Scheme = AnySingleFaced & Layout<ScryfallLayout.Scheme>;
 
   /** A card with the Vanguard layout. */
-  export type Vanguard = Layout<ScryfallLayout.Vanguard> &
-    SingleFace &
-    ScryfallCardFields.Gameplay.VanguardStats &
-    ScryfallCardFields.Gameplay.NoCombatStats;
+  export type Vanguard = AnySingleFaced & Layout<ScryfallLayout.Vanguard>;
 
   /** A card with the Token layout. */
-  export type Token = Layout<ScryfallLayout.Token> & SingleFace;
+  export type Token = AnySingleFaced & Layout<ScryfallLayout.Token>;
 
   /** A card with the Emblem layout. */
-  export type Emblem = Layout<ScryfallLayout.Emblem> & SingleFace;
+  export type Emblem = AnySingleFaced & Layout<ScryfallLayout.Emblem>;
 
   /** A card with the Augment layout. */
-  export type Augment = Layout<ScryfallLayout.Augment> & SingleFace;
+  export type Augment = AnySingleFaced & Layout<ScryfallLayout.Augment>;
 
   /** A card with the Host layout. */
-  export type Host = Layout<ScryfallLayout.Host> & SingleFace;
+  export type Host = AnySingleFaced & Layout<ScryfallLayout.Host>;
+}
+
+export namespace ScryfallCard {
+  type MultiFace<Face extends ScryfallCardFace.AbstractCardFace> = AbstractCard &
+    ScryfallCardFields.Gameplay.RootProperties &
+    ScryfallCardFields.Gameplay.CardSpecific &
+    ScryfallCardFields.Gameplay.CardFaces<Face> &
+    ScryfallCardFields.Print.RootProperties &
+    ScryfallCardFields.Print.CardSpecific;
+
+  /**
+   * Any split layout, either single sided or double sided. These will both have `card_faces`.
+   */
+  export type AnySplit = AnySingleSidedSplit | AnyDoubleSidedSplit;
+
+  /**
+   * Any single-sided split card. These all have `card_faces`, and the faces are both on the front.
+   *
+   * Examples: {@link ScryfallLayout.Split}, {@link ScryfallLayout.Flip}, {@link ScryfallLayout.Adventure}.
+   */
+  export type AnySingleSidedSplit = MultiFace<ScryfallCardFace.Split> &
+    Layout<ScryfallLayoutGroup.SingleSidedSplitType> &
+    ScryfallCardFields.Gameplay.CardSideSpecific &
+    ScryfallCardFields.Gameplay.CombatStats &
+    ScryfallCardFields.Print.CardSideSpecific &
+    ScryfallCardFields.Print.SingleSideOnly;
 
   /** A card with the Split layout. */
-  export type Split = Layout<ScryfallLayout.Split> & SingleSidedSplit;
+  export type Split = AnySingleSidedSplit & Layout<ScryfallLayout.Split>;
 
   /** A card with the Flip layout. */
-  export type Flip = Layout<ScryfallLayout.Flip> & SingleSidedSplit & ScryfallCardFields.Gameplay.CombatStats;
+  export type Flip = AnySingleSidedSplit & Layout<ScryfallLayout.Flip>;
 
   /** A card with the Adventure layout. */
-  export type Adventure = Layout<ScryfallLayout.Adventure> & SingleSidedSplit & ScryfallCardFields.Gameplay.CombatStats;
+  export type Adventure = AnySingleSidedSplit & Layout<ScryfallLayout.Adventure>;
+
+  /**
+   * Any double-sided split card. These all have `card_faces`, and the faces are on the obverse and reverse of the card.
+   *
+   * Examples: {@link ScryfallLayout.Transform}, {@link ScryfallLayout.ModalDfc}, {@link ScryfallLayout.DoubleFacedToken}.
+   */
+  export type AnyDoubleSidedSplit = MultiFace<ScryfallCardFace.DoubleSided> &
+    Layout<ScryfallLayoutGroup.DoubleSidedSplitType>;
 
   /** A card with the Transform layout. */
-  export type Transform = Layout<ScryfallLayout.Transform> & DoubleSidedSplit;
+  export type Transform = AnyDoubleSidedSplit & Layout<ScryfallLayout.Transform>;
 
   /** A card with the ModalDfc layout. */
-  export type ModalDfc = Layout<ScryfallLayout.ModalDfc> & DoubleSidedSplit;
+  export type ModalDfc = AnyDoubleSidedSplit & Layout<ScryfallLayout.ModalDfc>;
 
   /** A card with the DoubleFacedToken layout. */
-  export type DoubleFacedToken = Layout<ScryfallLayout.DoubleFacedToken> & DoubleSidedSplit;
+  export type DoubleFacedToken = AnyDoubleSidedSplit & Layout<ScryfallLayout.DoubleFacedToken>;
 
   /** A card with the ArtSeries layout. */
-  export type ArtSeries = Layout<ScryfallLayout.ArtSeries> & DoubleSidedSplit;
+  export type ArtSeries = AnyDoubleSidedSplit & Layout<ScryfallLayout.ArtSeries>;
+}
 
+export namespace ScryfallCard {
   /** A card with the ReversibleCard layout. */
   export type ReversibleCard = Layout<ScryfallLayout.ReversibleCard> &
     Omit<AbstractCard, "oracle_id"> &
@@ -155,66 +178,20 @@ export namespace ScryfallCard {
     ScryfallCardFields.Gameplay.CardFaces<ScryfallCardFace.Reversible> &
     ScryfallCardFields.Print.RootProperties &
     ScryfallCardFields.Print.CardSpecific;
+}
 
+export namespace ScryfallCard {
   /**
    * A card with an indeterminate layout.
    *
    * An object of this value may be any card at all.
    *
    * Since this may be of any layout, common fields are available, but layout-specific fields (e.g. card_faces) will be unavailable until you perform type narrowing on
    */
-  export type Any =
-    | Normal
-    | Meld
-    | Leveler
-    | Class
-    | Saga
-    | Mutate
-    | Prototype
-    | Battle
-    | Planar
-    | Scheme
-    | Vanguard
-    | Token
-    | Emblem
-    | Augment
-    | Host
-    | Split
-    | Flip
-    | Adventure
-    | Transform
-    | ModalDfc
-    | DoubleFacedToken
-    | ArtSeries
-    | ReversibleCard;
-
-  /**
-   * Any card with a single-faced layout. These all have a .
-   *
-   * Examples: {@link Normal}, {@link Mutate}, {@link Token}.
-   */
-  export type AnySingleFaced = Any & Layout<ScryfallLayoutGroup.SingleFaceType>;
-
-  /**
-   * Any multi-faced layout, which is any that would have a `card_faces` field.
-   *
-   * @see {@link AnySingleSidedSplit} is in this group.
-   * @see {@link AnyDoubleSidedSplit} is in this group.
-   * @see {@link ReversibleCard} is in this group.
-   */
-  export type AnyMultiFaced = Any & Layout<ScryfallLayoutGroup.MultiFaceType>;
-
-  /**
-   * Any single-sided split card. These all have `card_faces`, and the faces are both on the front.
-   *
-   * Examples: {@link Split}, {@link Flip}, {@link Adventure}.
-   */
-  export type AnySingleSidedSplit = Any & Layout<ScryfallLayoutGroup.SingleSidedSplitType>;
+  export type Any = AnySingleFaced | AnySingleSidedSplit | AnyDoubleSidedSplit | ReversibleCard;
 
   /**
-   * Any double-sided split card. These all have `card_faces`, and the faces are on the obverse and reverse of the card.
-   *
-   * Examples: {@link Transform}, {@link ModalDfc}, {@link DoubleFacedToken}.
+   * Any card that is multifaced: either a single or double sided split layout, or a reversible card.
    */
-  export type AnyDoubleSidedSplit = Any & Layout<ScryfallLayoutGroup.DoubleSidedSplitType>;
+  export type AnyMultiFaced = AnySingleSidedSplit | AnyDoubleSidedSplit | ReversibleCard;
 }