cards

Basic playing cards module

Install

$ npm install cards

Usage

var cards = require('cards');
 
// Create a new 52 card poker deck 
var deck = new cards.PokerDeck();
 
// Shuffle the deck 
deck.shuffleAll();
 
// Draw a card 
var card = deck.draw();
console.log(card);

There are multiple built-in deck types. These include PokerDeck, OldMaidDeck, EuchreDeck, BarajaDeck PinochelDeck, and PiquetDeck. The only one of these that can take any parameters is the poker deck which takes a config object, allowing the addition of jokers.

var deckWithJokers = new cards.PokerDeck({ jokers: 2 });

Optionally, you can also create an empty deck and add cards to it your self. This is done with the base Deck constructor.

var deck = new cards.Deck();
 
// The new deck is completely empty 
console.log(deck.cards.length);  // 0 
 
// Add a new card to the deck 
deck.add(new cards.Card('spade', 3));

You can extend the base constructor to create your own custom deck types.

// The generators object contains functions for creating new decks 
cards.generators.ourWeirdDeck = function(deck) {
    ['club', 'diamond', 'heart', 'spade'].forEach(function(suit) {
        [2, 4, 6, 8, 10, 'Q'].forEach(function(value) {
            deck.add(new cards.Card(suit, value));
        });
    });
};
 
// Create the new deck constructor and point it to our generator 
cards.Deck.createType('WeirdDeck', 'ourWeirdDeck');
 
// Now we can create instances of our new deck type 
var weirdDeck = new cards.WeirdDeck();

Each deck consists of three "piles" of cards. No card can appear in more than one pile at a time and every card exists in one of the three piles at all times. These piles are "deck", "held", and "discard". By default, all cards in a deck are in the deck pile. When a card is drawn, it is moved to the held pile and when discarded, it is moved to the discard pile.

var deck = new cards.PokerDeck();
 
deck.deck.length === 52;
deck.held.length === 0;
deck.discard.length === 0;
 
deck.draw();
 
deck.deck.length === 51;
deck.held.length === 1;
deck.discard.length === 0;
 
// This is a shortcut for deck.discard(deck.draw()) 
deck.drawToDiscard();
 
deck.deck.length === 50;
deck.held.length === 1;
deck.discard.length === 1;

The useArc4 flag changes how cards are shuffled. By default, the randomization needed for shuffling is creating using the built-in Math.random() function. By setting this flag to true, all shuffle functions will instead use the better (but slower) ARC4 PRNG.

The constructor for creating new playing card objects.

The suit of the card. The only suits created by the built-in types are "spade", "heart", "club", "diamond", and "other" (for special cards like jokers).

The value of the card. This value is cast to a string, so things like new Card("spade", 3) will work, but this property will produce the value "3" as a string.

The deck object that this card belongs to.

Get a unicode string representing the card, eg.

var card = new cards.Card("spade", 3);
 
card.unicodeString();  // "3♠" 

This constructor creates the "deck", "held", and "discard" piles inside of each deck. The pile constructor inherits from Array.

Empties out the pile and returns an array of the values removed.

Copy all values onto the end of another array (or array-like object).

Empty out the pile and append all of the values onto the end of another array (or array-like object).

Shift one value off of the pile and push it onto another array (or array-like object).

The base constructor for creating new decks of cards. The generator argument is either a string (the name of a function on the cards.generators object) or a function.

Adds a card to the deck. If the card is already in a deck, it will first be removed from that deck. The optional config object takes one property pile which controlls which of the three piles the card will be added to.

Removes a card from the deck.

Draws a card(s) from the "deck" pile, moving them into the "held" pile and returns it. If there are no cards left in the deck, a RangeError will be thrown. If a count value is given, that many cards will be drawn and returned in an array. If there are cards in the deck, but not enough to meet the count requirement, all of the remaining cards will be returned in an array and no error will be throw. As such, you should check the length of the array you get back when doing multiple card draws.

This method works the same as Deck::draw() except that cards are moved to "discard" instead of held.

Finds a card in the deck. If the argument given is a Card object, that specific card will be found and returned with some extra positional information (see below). An array argument can also be given, though, in the format [suit, value]. If this is the case, all matching cards will be found (there can be more than one of the same kind of card in a deck, for example, in a Pinochel deck where every card is duplicated).

var card = deck.draw();
 
var found = deck.find(card);
 
//  
// found = [ 
//   { 
//     pileName: String,  (eg. "deck" or "discard") 
//     pile: cards.Pile,  (the actual Pile object) 
//     index: Number,     (the card's index in the pile) 
//     card: cards.Card   (the actual Card object) 
//   } 
// ] 
// 
 
// You can also search for a card by description, like so: 
deck.find([ "spade", "A" ]);

Moves all cards back into the "deck" pile and shuffles.

Shuffles all cards remaining in the "deck" pile.

Shuffles all cards in the "discard" pile and then appends them to the deck.

Moves all cards from the "held" pile to the "discard" pile.

Creates a new constructor at cards[name] that will create a new deck using the given generator. If a constructor function is given it will be called after invoking the Deck constructor.

Creates a new Poker deck. If the config object is given, the number given in the jokers property will determine the number of joker cards added to the deck.

Creates a new Old Maid deck: a standard Poker deck with no jokers and a special card called a "maid" card.

Creates a new Euchre deck.

Creates a new Baraja deck.

Creates a new Pinochel deck.

Creates a new Piquet deck.

MIT License

Copyright (c) 2012 James Brumond

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.