feat: Allow a user to filters elements on the API (#275)

src/models/Card.ts

@@ -0,0 +1,198 @@
+import CardResume from './CardResume'
+import type { Variants } from './Other'
+import type TCGdexSet from './Set'
+import type SetResume from './SetResume'
+
+// TODO: sort elements by alphabetical order
+export default class Card extends CardResume {
+	/**
+	 * Card illustrator
+	 */
+	public illustrator?: string
+
+	/**
+	 * Card Rarity
+	 *
+	 * - None https://www.tcgdex.net/database/sm/smp/SM01
+	 * - Common https://www.tcgdex.net/database/xy/xy9/1
+	 * - Uncommon https://www.tcgdex.net/database/xy/xy9/2
+	 * - Rare https://www.tcgdex.net/database/xy/xy9/3
+	 * - Ultra Rare
+	 * - Secret Rare
+	 */
+	public rarity!: string
+
+	/**
+	 * Card Category
+	 *
+	 * - Pokemon
+	 * - Trainer
+	 * - Energy
+	 */
+	public category!: string
+
+	/**
+	 * Card Variants (Override Set Variants)
+	 */
+	public variants?: Variants
+
+	/**
+	 * Card Set
+	 */
+	public set!: SetResume
+
+	/**
+	 * Pokemon only elements
+	 */
+
+	/**
+	 * Pokemon Pokedex ID
+	 */
+	public dexId?: Array<number>
+
+	/**
+	 * Pokemon HP
+	 */
+	public hp?: number
+
+	/**
+	 * Pokemon Types
+	 * ex for multiple https://www.tcgdex.net/database/ex/ex13/17
+	 */
+	public types?: Array<string>
+
+	/**
+	 * Pokemon Sub Evolution
+	 */
+	public evolveFrom?: string
+
+	/**
+	 * Pokemon Weight
+	 */
+	public weight?: string
+
+	/**
+	 * Pokemon Description
+	 */
+	public description?: string
+
+	/**
+	 * Level of the Pokemon
+	 *
+	 * NOTE: can be equal to 'X' when the pokemon is a LEVEL-UP one
+	 */
+	public level?: number | string
+
+	/**
+	 * Pokemon Stage
+	 *
+	 * - Basic https://www.tcgdex.net/database/xy/xy9/1
+	 * - BREAK https://www.tcgdex.net/database/xy/xy9/18
+	 * - LEVEL-UP https://www.tcgdex.net/database/dp/dp1/121
+	 * - MEGA https://www.tcgdex.net/database/xy/xy1/2
+	 * - RESTORED https://www.tcgdex.net/database/bw/bw5/53
+	 * - Stage1 https://www.tcgdex.net/database/xy/xy9/2
+	 * - Stage2 https://www.tcgdex.net/database/xy/xy9/3
+	 * - VMAX https://www.tcgdex.net/database/swsh/swsh1/50
+	 */
+	public stage?: string
+
+	/**
+	 * Card Suffix
+	 *
+	 * - EX https://www.tcgdex.net/database/ex/ex2/94
+	 * - GX https://www.tcgdex.net/database/sm/sm12/4
+	 * - V https://www.tcgdex.net/database/swsh/swsh1/1
+	 * - Legend https://www.tcgdex.net/database/hgss/hgss1/114
+	 * - Prime https://www.tcgdex.net/database/hgss/hgss2/85
+	 * - SP https://www.tcgdex.net/database/pl/pl1/7
+	 * - TAG TEAM-GX https://www.tcgdex.net/database/sm/sm12/226
+	 */
+	public suffix?: string
+
+	/**
+	 * Pokemon Held Item
+	 *
+	 * ex https://www.tcgdex.net/database/dp/dp2/75
+	 */
+	public item?: {
+		name: string
+		effect: string
+	}
+
+	/**
+	 * Pokemon Abilities
+	 *
+	 * multi abilities ex https://www.tcgdex.net/database/ex/ex15/10
+	 */
+	public abilities?: Array<{
+		type: string
+		name: string
+		effect: string
+	}>
+
+	/**
+	 * Pokemon Attacks
+	 */
+	public attacks?: Array<{
+		cost?: Array<string>
+		name: string
+		effect?: string
+		damage?: string | number
+	}>
+
+	/**
+	 * Pokemon Weaknesses
+	 */
+	public weaknesses?: Array<{
+		type: string
+		value?: string
+	}>
+
+	public resistances?: Array<{
+		type: string
+		value?: string
+	}>
+
+	public retreat?: number
+
+	// Trainer/Energy
+	public effect?: string
+
+	// Trainer Only
+	public trainerType?: string
+
+	// Energy Only
+	public energyType?: string
+
+	/**
+	 * Define the rotation mark on cards >= Sword & Shield
+	 */
+	public regulationMark?: string
+
+	/**
+	 * Card ability to be played in official tournaments
+	 *
+	 * Note: all cards are avaialable to play in unlimited tournaments
+	 */
+	public legal!: {
+
+		/**
+		 * Ability to play in standard tournaments
+		 */
+		standard: boolean
+
+		/**
+		 * Ability to play in expanded tournaments
+		 */
+		expanded: boolean
+	}
+
+	public override async getCard(): Promise<Card> {
+		return this
+	}
+
+	public async getSet(): Promise<TCGdexSet> {
+		return (await this.sdk.set.get(this.set.id))!
+	}
+}

src/models/CardResume.ts

@@ -0,0 +1,47 @@
+import type { Extension, Quality } from '../interfaces'
+import type Card from './Card'
+import Model from './Model'
+
+export default class CardResume extends Model {
+	/**
+	 * Globally unique card ID based on the set ID and the cards ID within the set
+	 */
+	public id!: string
+
+	/**
+	 * Card image url without the extension and quality
+	 *
+	 * @see {@link getImageURL}
+	 */
+	public image?: string
+
+	/**
+	 * ID indexing this card within its set, usually just its number
+	 */
+	public localId!: string
+
+	/**
+	 * Card Name (Including the suffix if next to card name)
+	 */
+	public name!: string
+
+	/**
+	 * the the Card Image full URL
+	 *
+	 * @param {Quality} quality the quality you want your image to be in
+	 * @param {Extension} extension extension you want you image to be
+	 * @return the full card URL
+	 */
+	public getImageURL(quality: Quality = 'high', extension: Extension = 'png'): string {
+		return `${this.image}/${quality}.${extension}`
+	}
+
+	/**
+	 * Get the full Card
+	 *
+	 * @return the full card if available
+	 */
+	public async getCard(): Promise<Card> {
+		return (await this.sdk.card.get(this.id))!
+	}
+}

src/models/Model.ts

@@ -0,0 +1,28 @@
+import { objectLoop } from '@dzeio/object-util'
+import type TCGdex from '../tcgdex'
+
+export default abstract class Model {
+
+	public constructor(
+		protected readonly sdk: TCGdex
+	) { }
+
+	/**
+	 * build a model depending on the data given
+	 * @param model the model to build
+	 * @param data the data to fill it with
+	 */
+	public static build<T extends Model>(model: T, data?: object): T {
+		if (!data) {
+			throw new Error('data is necessary.')
+		}
+		model.fill(data)
+		return model
+	}
+
+	protected fill(obj: object) {
+		objectLoop(obj, (value, key) => {
+			(this as object)[key] = value
+		})
+	}
+}

src/models/Other.d.ts

@@ -0,0 +1,6 @@
+export interface Variants {
+	normal?: boolean
+	reverse?: boolean
+	holo?: boolean
+	firstEdition?: boolean
+}

src/models/Serie.ts

@@ -0,0 +1,21 @@
+import { objectLoop } from '@dzeio/object-util'
+import Model from './Model'
+import SerieResume from './SerieResume'
+import SetResume from './SetResume'
+
+export default class Serie extends SerieResume {
+	public sets!: Array<SetResume>
+
+	protected fill(obj: object): void {
+		objectLoop(obj, (value, key) => {
+			switch (key) {
+				case 'sets':
+					this.sets = (value as Array<any>).map((it) => Model.build(new SetResume(this.sdk), it))
+					break
+				default:
+					this[key] = value
+					break
+			}
+		})
+	}
+}

src/models/SerieResume.ts

@@ -0,0 +1,24 @@
+import type { Extension } from '../interfaces'
+import Model from './Model'
+import type Serie from './Serie'
+
+export default class SerieResume extends Model {
+	public id!: string
+	public name!: string
+	public logo?: string
+
+	/**
+	 * the the Card Image full URL
+	 *
+	 * @param {Quality} quality the quality you want your image to be in
+	 * @param {Extension} extension extension you want you image to be
+	 * @return the full card URL
+	 */
+	public getImageURL(extension: Extension = 'png'): string {
+		return `${this.logo}.${extension}`
+	}
+
+	public async getSerie(): Promise<Serie> {
+		return (await this.sdk.serie.get(this.id))!
+	}
+}

src/models/Set.ts

@@ -0,0 +1,89 @@
+import { objectLoop } from '@dzeio/object-util'
+import CardResume from './CardResume'
+import Model from './Model'
+import type { Variants } from './Other'
+import type SerieResume from './SerieResume'
+
+// biome-ignore lint/suspicious/noShadowRestrictedNames: <explanation>
+export default class Set extends Model {
+	public id!: string
+	public name!: string
+	public logo?: string
+	public symbol?: string
+	public serie!: SerieResume
+	public tcgOnline?: string
+	public variants?: Variants
+
+	public releaseDate!: string
+
+	/**
+	 * Designate if the set is usable in tournaments
+	 *
+	 * Note: this is specific to the set and if a
+	 * card is banned from the set it will still be true
+	 */
+	public legal!: {
+
+		/**
+		 * Ability to play in standard tournaments
+		 */
+		standard: boolean
+
+		/**
+		 * Ability to play in expanded tournaments
+		 */
+		expanded: boolean
+	}
+
+	public cardCount!: {
+
+		/**
+		 * total of number of cards
+		 */
+		total: number
+
+		/**
+		 * number of cards officialy (on the bottom of each cards)
+		 */
+		official: number
+
+		/**
+		 * number of cards having a normal version
+		 */
+		normal: number
+
+		/**
+		 * number of cards having an reverse version
+		 */
+		reverse: number
+
+		/**
+		 * number of cards having an holo version
+		 */
+		holo: number
+
+		/**
+		 * Number of possible cards
+		 */
+		firstEd?: number
+	}
+
+	public cards!: Array<CardResume>
+
+	public async getSerie() {
+		return this.sdk.serie.get(this.serie.id)
+	}
+
+	protected fill(obj: object): void {
+		objectLoop(obj, (value, key) => {
+			switch (key) {
+				case 'cards':
+					this.cards = (value as Array<any>).map((it) => Model.build(new CardResume(this.sdk), it))
+					break
+				default:
+					this[key] = value
+					break
+			}
+		})
+	}
+}

src/models/SetResume.ts

@@ -0,0 +1,25 @@
+import Model from './Model'
+import type TCGdexSet from './Set'
+
+export default class SetResume extends Model {
+	public id!: string
+	public name!: string
+	public logo?: string
+	public symbol?: string
+	public cardCount!: {
+
+		/**
+		 * total of number of cards
+		 */
+		total: number
+
+		/**
+		  * number of cards officialy (on the bottom of each cards)
+		  */
+		official: number
+	}
+
+	public async getSet(): Promise<TCGdexSet> {
+		return (await this.sdk.set.get(this.id))!
+	}
+}

src/models/StringEndpoint.ts

@@ -0,0 +1,21 @@
+import { objectLoop } from '@dzeio/object-util'
+import CardResume from './CardResume'
+import Model from './Model'
+
+export default class StringEndpoint extends Model {
+	public name!: string
+	public cards!: Array<CardResume>
+
+	protected fill(obj: object): void {
+		objectLoop(obj, (value, key) => {
+			switch (key) {
+				case 'cards':
+					this.cards = (value as Array<any>).map((it) => Model.build(new CardResume(this.sdk), it))
+					break
+				default:
+					this[key] = value
+					break
+			}
+		})
+	}
+}