mv layout, type narrowing tests

Author: scarletcs

README.md

@@ -1,10 +1,17 @@
 # Scryfall API types
 
-This library documents the definitive comprehensive typings of the Scryfall API for use in Typescript & Javascript projects.
+This library documents the definitive comprehensive typings of [the Scryfall API][api] for use in Typescript & Javascript projects.
 
 This library uses [semver] for versioning. These versions only describe this library, not the Scryfall API as a whole.
 
 [semver]: https://semver.org/
+[api]: https://scryfall.com/docs/api
+
+## Usage
+
+Each object or type exported by this library corresponds to a Scryfall API object.
+
+-
 
 ## Details
 

__test__/Card/narrowing/TypeNarrowing.ts

@@ -0,0 +1,106 @@
+import { ScryfallCard, ScryfallLayout } from "src";
+
+const anyCard = {} as ScryfallCard.Any;
+
+if (anyCard.layout === ScryfallLayout.Normal) {
+  const specific: ScryfallCard.Normal = anyCard;
+  const grouped: ScryfallCard.AnySingleFaced = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.Meld) {
+  const specific: ScryfallCard.Meld = anyCard;
+  const grouped: ScryfallCard.AnySingleFaced = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.Leveler) {
+  const specific: ScryfallCard.Leveler = anyCard;
+  const grouped: ScryfallCard.AnySingleFaced = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.Class) {
+  const specific: ScryfallCard.Class = anyCard;
+  const grouped: ScryfallCard.AnySingleFaced = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.Saga) {
+  const specific: ScryfallCard.Saga = anyCard;
+  const grouped: ScryfallCard.AnySingleFaced = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.Mutate) {
+  const specific: ScryfallCard.Mutate = anyCard;
+  const grouped: ScryfallCard.AnySingleFaced = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.Prototype) {
+  const specific: ScryfallCard.Prototype = anyCard;
+  const grouped: ScryfallCard.AnySingleFaced = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.Battle) {
+  const specific: ScryfallCard.Battle = anyCard;
+  const grouped: ScryfallCard.AnySingleFaced = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.Planar) {
+  const specific: ScryfallCard.Planar = anyCard;
+  const grouped: ScryfallCard.AnySingleFaced = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.Scheme) {
+  const specific: ScryfallCard.Scheme = anyCard;
+  const grouped: ScryfallCard.AnySingleFaced = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.Vanguard) {
+  const specific: ScryfallCard.Vanguard = anyCard;
+  const grouped: ScryfallCard.AnySingleFaced = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.Token) {
+  const specific: ScryfallCard.Token = anyCard;
+  const grouped: ScryfallCard.AnySingleFaced = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.Emblem) {
+  const specific: ScryfallCard.Emblem = anyCard;
+  const grouped: ScryfallCard.AnySingleFaced = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.Augment) {
+  const specific: ScryfallCard.Augment = anyCard;
+  const grouped: ScryfallCard.AnySingleFaced = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.Host) {
+  const specific: ScryfallCard.Host = anyCard;
+  const grouped: ScryfallCard.AnySingleFaced = anyCard;
+}
+
+if (anyCard.layout === ScryfallLayout.Split) {
+  const specific: ScryfallCard.Split = anyCard;
+  const anyMultiFaced: ScryfallCard.AnyMultiFaced = anyCard;
+  const anySingleSidedSplit: ScryfallCard.AnySingleSidedSplit = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.Flip) {
+  const specific: ScryfallCard.Flip = anyCard;
+  const anyMultiFaced: ScryfallCard.AnyMultiFaced = anyCard;
+  const anySingleSidedSplit: ScryfallCard.AnySingleSidedSplit = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.Adventure) {
+  const specific: ScryfallCard.Adventure = anyCard;
+  const anyMultiFaced: ScryfallCard.AnyMultiFaced = anyCard;
+  const anySingleSidedSplit: ScryfallCard.AnySingleSidedSplit = anyCard;
+}
+
+if (anyCard.layout === ScryfallLayout.Transform) {
+  const specific: ScryfallCard.Transform = anyCard;
+  const anyMultiFaced: ScryfallCard.AnyMultiFaced = anyCard;
+  const anyDoubleSidedSplit: ScryfallCard.AnyDoubleSidedSplit = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.ModalDfc) {
+  const specific: ScryfallCard.ModalDfc = anyCard;
+  const anyMultiFaced: ScryfallCard.AnyMultiFaced = anyCard;
+  const anyDoubleSidedSplit: ScryfallCard.AnyDoubleSidedSplit = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.DoubleFacedToken) {
+  const specific: ScryfallCard.DoubleFacedToken = anyCard;
+  const anyMultiFaced: ScryfallCard.AnyMultiFaced = anyCard;
+  const anyDoubleSidedSplit: ScryfallCard.AnyDoubleSidedSplit = anyCard;
+}
+if (anyCard.layout === ScryfallLayout.ArtSeries) {
+  const specific: ScryfallCard.ArtSeries = anyCard;
+  const anyMultiFaced: ScryfallCard.AnyMultiFaced = anyCard;
+  const anyDoubleSidedSplit: ScryfallCard.AnyDoubleSidedSplit = anyCard;
+}
+
+if (anyCard.layout === ScryfallLayout.ReversibleCard) {
+  const specific: ScryfallCard.ReversibleCard = anyCard;
+  const anyMultiFaced: ScryfallCard.AnyMultiFaced = anyCard;
+}

package.json

@@ -1,8 +1,8 @@
 {
-  "name": "api-types",
-  "version": "1.0.0",
+  "name": "@scryfall/api-types",
+  "version": "0.0.1-rc.0",
   "description": "Type definitions for the Scryfall API",
-  "main": "index.d.ts",
+  "main": "index.ts",
   "scripts": {
     "test": "npm run test:lib && npm run test:tests",
     "test:lib": "tsc -p tsconfig.lib.json --noEmit",
@@ -14,7 +14,7 @@
     "types",
     "typescript"
   ],
-  "author": "Sammy",
+  "author": "scarletcs",
   "license": "MIT",
   "devDependencies": {
     "@typescript-eslint/eslint-plugin": "^6.7.4",

src/objects/Card/Card.ts

@@ -1,16 +1,21 @@
 import { ScryfallObject } from "../Object";
-import { ScryfallCardLayout } from "./values/CardLayout";
+import { ScryfallLayout, ScryfallLayoutGroup } from "./values";
 import { ScryfallCardFace } from "./CardFace";
 import { ScryfallCardFields } from "./CardFields";
 
-type LayoutType<T extends ScryfallCardLayout> = Pick<ScryfallCardFields.Core.All, "layout"> & {
+type Layout<T extends ScryfallLayout> = Pick<ScryfallCardFields.Core.All, "layout"> & {
   layout: T | `${T}`;
 };
 
+/**
+ *
+ */
 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> &
     ScryfallCardFields.Gameplay.RootProperties &
     ScryfallCardFields.Gameplay.CardSpecific &
     ScryfallCardFields.Gameplay.CardFaceSpecific &
@@ -22,73 +27,96 @@ export namespace ScryfallCard {
     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>;
+  type DoubleSidedSplit = MultiFace<ScryfallCardFace.DoubleSided> & Layout<ScryfallLayoutGroup.DoubleSidedSplitType>;
 
   type AlwaysOversized = {
     oversized: true;
   };
 
-  export type Normal = LayoutType<ScryfallCardLayout.Normal> & SingleFace;
+  /** A card with the Normal layout. */
+  export type Normal = Layout<ScryfallLayout.Normal> & SingleFace;
 
-  export type Split = LayoutType<ScryfallCardLayout.Split> & SingleSidedSplit;
+  /** A card with the Meld layout. */
+  export type Meld = Layout<ScryfallLayout.Meld> & SingleFace;
 
-  export type Flip = LayoutType<ScryfallCardLayout.Flip> & SingleSidedSplit & ScryfallCardFields.Gameplay.CombatStats;
+  /** A card with the Leveler layout. */
+  export type Leveler = Layout<ScryfallLayout.Leveler> & SingleFace;
 
-  export type Transform = LayoutType<ScryfallCardLayout.Transform> & DoubleSidedSplit;
+  /** A card with the Class layout. */
+  export type Class = Layout<ScryfallLayout.Class> & SingleFace;
 
-  export type ModalDfc = LayoutType<ScryfallCardLayout.ModalDfc> & DoubleSidedSplit;
+  /** A card with the Saga layout. */
+  export type Saga = Layout<ScryfallLayout.Saga> & SingleFace;
 
-  export type Meld = LayoutType<ScryfallCardLayout.Meld> & SingleFace;
+  /** A card with the Mutate layout. */
+  export type Mutate = Layout<ScryfallLayout.Mutate> & SingleFace;
 
-  export type Leveler = LayoutType<ScryfallCardLayout.Leveler> & SingleFace;
+  /** A card with the Prototype layout. */
+  export type Prototype = Layout<ScryfallLayout.Prototype> & SingleFace;
 
-  export type Class = LayoutType<ScryfallCardLayout.Class> & SingleFace;
+  /** A card with the Battle layout. */
+  export type Battle = Layout<ScryfallLayout.Battle> & SingleFace;
 
-  export type Saga = LayoutType<ScryfallCardLayout.Saga> & SingleFace;
+  /** A card with the Planar layout. */
+  export type Planar = Layout<ScryfallLayout.Planar> & SingleFace & AlwaysOversized;
 
-  export type Adventure = LayoutType<ScryfallCardLayout.Adventure> &
-    SingleSidedSplit &
-    ScryfallCardFields.Gameplay.CombatStats;
+  /** A card with the Scheme layout. */
+  export type Scheme = Layout<ScryfallLayout.Scheme> & SingleFace & AlwaysOversized;
 
-  export type Mutate = LayoutType<ScryfallCardLayout.Mutate> & SingleFace;
+  /** A card with the Vanguard layout. */
+  export type Vanguard = Layout<ScryfallLayout.Vanguard> &
+    SingleFace &
+    ScryfallCardFields.Gameplay.VanguardStats &
+    ScryfallCardFields.Gameplay.NoCombatStats;
 
-  export type Prototype = LayoutType<ScryfallCardLayout.Prototype> & SingleFace;
+  /** A card with the Token layout. */
+  export type Token = Layout<ScryfallLayout.Token> & SingleFace;
 
-  export type Battle = LayoutType<ScryfallCardLayout.Battle> & SingleFace;
+  /** A card with the Emblem layout. */
+  export type Emblem = Layout<ScryfallLayout.Emblem> & SingleFace;
 
-  export type Planar = LayoutType<ScryfallCardLayout.Planar> & SingleFace & AlwaysOversized;
+  /** A card with the Augment layout. */
+  export type Augment = Layout<ScryfallLayout.Augment> & SingleFace;
 
-  export type Scheme = LayoutType<ScryfallCardLayout.Scheme> & SingleFace & AlwaysOversized;
+  /** A card with the Host layout. */
+  export type Host = Layout<ScryfallLayout.Host> & SingleFace;
 
-  export type Vanguard = LayoutType<ScryfallCardLayout.Vanguard> &
-    SingleFace &
-    ScryfallCardFields.Gameplay.VanguardStats &
-    ScryfallCardFields.Gameplay.NoCombatStats;
+  /** A card with the Split layout. */
+  export type Split = Layout<ScryfallLayout.Split> & SingleSidedSplit;
 
-  export type Token = LayoutType<ScryfallCardLayout.Token> & SingleFace;
+  /** A card with the Flip layout. */
+  export type Flip = Layout<ScryfallLayout.Flip> & SingleSidedSplit & ScryfallCardFields.Gameplay.CombatStats;
 
-  export type DoubleFacedToken = LayoutType<ScryfallCardLayout.DoubleFacedToken> & DoubleSidedSplit;
+  /** A card with the Adventure layout. */
+  export type Adventure = Layout<ScryfallLayout.Adventure> & SingleSidedSplit & ScryfallCardFields.Gameplay.CombatStats;
 
-  export type Emblem = LayoutType<ScryfallCardLayout.Emblem> & SingleFace;
+  /** A card with the Transform layout. */
+  export type Transform = Layout<ScryfallLayout.Transform> & DoubleSidedSplit;
 
-  export type Augment = LayoutType<ScryfallCardLayout.Augment> & SingleFace;
+  /** A card with the ModalDfc layout. */
+  export type ModalDfc = Layout<ScryfallLayout.ModalDfc> & DoubleSidedSplit;
 
-  export type Host = LayoutType<ScryfallCardLayout.Host> & SingleFace;
+  /** A card with the DoubleFacedToken layout. */
+  export type DoubleFacedToken = Layout<ScryfallLayout.DoubleFacedToken> & DoubleSidedSplit;
 
-  export type ArtSeries = LayoutType<ScryfallCardLayout.ArtSeries> & DoubleSidedSplit;
+  /** A card with the ArtSeries layout. */
+  export type ArtSeries = Layout<ScryfallLayout.ArtSeries> & DoubleSidedSplit;
 
-  export type ReversibleCard = LayoutType<ScryfallCardLayout.ReversibleCard> &
+  /** A card with the ReversibleCard layout. */
+  export type ReversibleCard = Layout<ScryfallLayout.ReversibleCard> &
     Omit<AbstractCard, "oracle_id"> &
     ScryfallCardFields.Gameplay.RootProperties &
     Omit<ScryfallCardFields.Gameplay.CardSpecific, "type_line" | "cmc"> &
@@ -98,26 +126,56 @@ export namespace ScryfallCard {
 
   export type Any =
     | Normal
-    | Split
-    | Flip
-    | Transform
-    | ModalDfc
     | Meld
     | Leveler
     | Class
     | Saga
-    | Adventure
     | Mutate
     | Prototype
     | Battle
     | Planar
     | Scheme
     | Vanguard
     | Token
-    | DoubleFacedToken
     | 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>;
+
+  /**
+   * 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}.
+   */
+  export type AnyDoubleSidedSplit = Any & Layout<ScryfallLayoutGroup.DoubleSidedSplitType>;
 }

src/objects/Card/CardFields.ts

@@ -2,7 +2,7 @@ import {
   ScryfallFormat,
   ScryfallLegalityLike,
   ScryfallLanguageCodeLike,
-  ScryfallCardLayoutLike,
+  ScryfallLayoutLike,
   ScryfallColors,
   ScryfallImageSize,
   ScryfallBorderColorLike,
@@ -33,7 +33,7 @@ export namespace ScryfallCardFields.Core {
     /** A language code for this printing. */
     lang: ScryfallLanguageCodeLike;
     /** A code for this card’s layout. */
-    layout: ScryfallCardLayoutLike;
+    layout: ScryfallLayoutLike;
     /** A link to where you can begin paginating all re/prints for this card on Scryfall’s API. */
     prints_search_uri: Uri;
     /** A link to this card’s rulings list on Scryfall’s API. */

src/objects/Card/index.ts

@@ -2,3 +2,5 @@ export * from "./Card";
 export * from "./CardFace";
 export * from "./CardFields";
 export * from "./RelatedCard";
+
+export * from "./values";