npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2025 – Pkg Stats / Ryan Hefner

card-sharp

v0.2.4

Published

A utility for simulating a deck of playing cards in Node.js

Downloads

13

Readme

Card Sharp

Card Sharp is a utility for simulating a deck of playing cards in Node.js.
It is a work in progress and may change significantly before it reaches version 1.0.

Quick Start

To get started using Card Sharp, you can use the default ESM export to instantiate a new deck.

Initialize deck (ESM)

import sharp from "card-sharp";

let deck = sharp();

console.log(deck.cards.length); // the default deck starts with 52 cards

CommonJS users can require the module, but should be advised that the module export is a promise which will resolve into an object containing the ESM module's named exports.

Initialize deck (CJS)

require("card-sharp").then((sharp) => {
    let deck = sharp.init(); // the same 52-card deck
});

Either method will give you a simulated deck of 52 French-style playing cards, including ace through king in four suits: clubs (♣︎), diamonds (♦︎), hearts (♥︎), and spades (♠︎). Jokers are not included in the default deck.

From there, you can draw cards from this deck, return them to a discard pile, shuffle the deck (optionally returning the discard pile to the deck), or deal cards to multiple players in turn.

Note that the deck is not initially shuffled.

Shuffle, draw, and discard

deck.shuffle(); // initial shuffle

let hand = deck.draw(5); // take 5 cards from the deck

console.log(hand.length);       // there are now 5 cards in your hand
console.log(deck.cards.length); // there are 47 cards left in the deck

deck.discard(hand); // discard all 5 cards in your hand

console.log(hand.length);          // your hand is now empty
console.log(deck.cards.length);    // there are still 47 cards in the deck
console.log(deck.discards.length); // there are 5 cards in the discard pile

deck.shuffle(true); // shuffle again, including discards

console.log(deck.cards.length); // there are 52 cards in the deck again

Deal to multiple players

let players = deck.deal(2, 5); // deal two cards each to 5 separate players

deck.discard(players[3]); // player #4 folds

let community = deck.draw(3); // deal the flop

Exports

Card Sharp's default export is an init function which sets up a default 52-card deck for you. Additionally, the package entrypoint has the following named exports:

  • Card - the class representing a single playing card
  • Deck - the class representing a deck of playing cards
  • config - a configuration object containing data which can be used to set up a deck
  • init - the initialization function which is also the default export

Configuration

Card Sharp is designed to give you significant flexibility over the deck you build. Two pre-defined deck configurations are provided: a 52-card standard deck (A-K in four suits) and a 54-card version which is the same as the standard deck but additionally includes two jokers. If you call the init function without any params, it will return a standard 52-card deck.

import { config, init } from "card-sharp";

let std_deck = init({ "cards": config.decks.standard }),        // same as default
    jok_deck = init({ "cards": config.decks.standard_jokers }); // adds 2 jokers

Instead of using a prefab deck, you can build your own by providing an array of card option objects to the init function:

const custom_card_set = [ { "rank": "a", "suit": "c" }, { "rank": "2", "suit": "c" }, ... ];

let custom_deck = init(custom_card_set);

Card API

Card class

A single French-style playing card.

new Card(user_opts)

| Param | Type | Description | | --- | --- | --- | | user_opts | object | User options for this card |

Card constructor

card.toString()

String conversion method

Returns: string - The card ID

Card.fromArray(cards)

| Param | Type | Description | | --- | --- | --- | | cards | array | The list of card options |

Generate cards from an array of objects

Returns: array.<Card> - The generated cards

Deck API

Deck class

A deck of French-style playing cards.

new Deck(cards)

| Param | Type | Description | | --- | --- | --- | | cards | array | The cards to add to the deck |

Deck constructor

deck.add(cards)

| Param | Type | Description | | --- | --- | --- | | cards | array | The cards to add |

Add one or more cards to the deck

Returns: Deck - This deck

deck.addOne(card)

| Param | Type | Description | | --- | --- | --- | | card | Card | The card to add |

Add one (and only one) card to the deck

Returns: Deck - This deck

deck.deal(num_cards, num_players)

| Param | Type | Default | Description | | --- | --- | --- | --- | | num_cards | number | 1 | The number of cards to deal to each player | | num_players | number | 1 | The number of players who get cards |

Deal one or more cards to multiple players

A card is dealt to each player in turn. If multiple cards are to be dealt to each player, the first player doesn't get a second card until every other player has gotten one.

When dealing three cards each to three players (A, B, and C), the order of cards dealt would be A1, B1, C1, A2, B2, C2, A3, B3, C3.

The output is organized by player:

 [
     [ card1, card4, card7 ], // player A's cards
     [ card2, card5, card8 ], // player B's cards
     [ card3, card6, card9 ]  // player C's cards
 ]

Returns: array.<array.<Card>> - A nested array of cards

deck.discard(cards)

| Param | Type | Description | | --- | --- | --- | | cards | array | The cards to discard |

Discard one or more cards

Returns: Deck - This deck

deck.discardOne(card)

| Param | Type | Description | | --- | --- | --- | | card | Card | The card to discard |

Discard one (and only one) card

Returns: Deck - This deck

deck.draw(count)

| Param | Type | Default | Description | | --- | --- | --- | --- | | count | number | 1 | The number of cards to draw |

Draw one or more cards from the deck

Returns: array.<Card> - The drawn cards

deck.drawOne()

Draw one (and only one) card from the deck

Returns: Card - The drawn card

deck.remove(cards)

| Param | Type | Description | | --- | --- | --- | | cards | array | The cards to remove |

Remove one or more cards from the deck

Returns: Deck - This deck

deck.removeOne(card)

| Param | Type | Description | | --- | --- | --- | | card | Card | The card to remove |

Remove one (and only one) card from the deck

Returns: Deck - This deck

deck.shuffle(include_discards)

| Param | Type | Default | Description | | --- | --- | --- | --- | | include_discards | bool | false | Return all cards from the discard pile to the deck prior to shuffling |

Shuffle the deck

Returns: Deck - This (shuffled) deck