couponjs
v0.15.0
Published
Generate coupons.
Downloads
269
Maintainers
Readme
couponjs
Generate coupons.
Use case
Import. Configure. Generate.
This is a simple project to generate coupons. Lots of coupons.
Import the package, configure (this is optional), generate (1 or more coupons) and then use the coupons however you like (save in database, etc).
Table of Contents
- Getting Started
- Generate coupon
- Coupon engine configuration
- Configuration to generate coupons
- Possible number of coupons
- Storage size
- Older version
- License
- Donate
Getting Started
Install
npm i couponjs
Require
// ESM
import CouponJS from 'couponjs';
// CommonJs
const { CouponJS } = require('couponjs');
Generate coupon
Create an object.
const coupon = new CouponJS();
Now, call the generate
method.
const myCoupon = coupon.generate();
The above code will produce coupon like ASDFGH
.
By default, generate
will return coupon code of length 6 using uppercase alphabet.
Coupon engine configuration
We can configure the CouponJS engine to get reponse in a different format.
The syntax looks like the following.
const coupon = new CouponJS({ key: value });
Verbose
If we want verbose response (success/error) then we can set the field verbose
to true.
Default value: false
const coupon = new CouponJS({ verbose: true });
If set to true
then success response will look like the following.
{
status: 'success',
numberOfCoupons: 1,
coupons: ['QWERTY']
}
And error response will look like the following.
{
status: 'error',
error: {
type: 'COUPONJS_VALIDATION_ERROR',
message: 'Invalid characters used in the format rule.',
errors: [
{
field: 'format',
type: 'COUPONJS_FORMAT_ERROR',
message: 'Invalid characters used in the format rule. Only x and - are allowed. And only one - inbetween like xxx-xxx.'
}
]
}
}
Log Performance
To log the performance we have to set the option logPerformance
to true
.
Default value: false
Depends on: verbose to be true
.
Syntax:
const coupon = new CouponJS({
verbose: true,
logPerformance: true
});
This will return success response like the following.
{
"status": "success",
"numberOfCoupons": 1,
"coupons": [
"QWERTY"
],
"performance": {
"duration": {
"nano": 730779,
"micro": 730.779,
"milli": 0.730779,
"second": 0.000730779
}
}
}
And error response like the following.
{
"status": "error",
"error": {
"message": "Invalid characters used in the format rule.",
"type": "COUPONJS_VALIDATION_ERROR",
"errors": [
{
"type": "COUPONJS_FORMAT_ERROR",
"field": "format",
"message": "Invalid characters used in the format rule. Only x and - are allowed. And only one - inbetween like xxx-xxx."
}
]
},
"performance": {
"duration": {
"nano": 1313840,
"micro": 1313.84,
"milli": 1.31384,
"second": 0.00131384
}
}
}
Maximum number of coupons to generate
By default, we can generate 100000
coupons.
If we want to increase or decrease the number of coupons that can be generated then we set the maxNumberOfCouponsToGenerate
field.
It takes an integer value greater than 0.
Default value: 100000
Syntax:
const coupon = new CouponJS({
maxNumberOfCouponsToGenerate: 100
});
Configuration to generate coupons
We can pass different options to configure the engine to generate coupons as per our settings.
Eample:
const myCoupon = coupon.generate({
length: 8
});
Options that we can use are listed below.
Coupon of length N
To generate coupon of a given length we pass the following option to the generate
method.
const myCoupon = coupon.generate({
length: 8
});
Where, 8 in the above code represent the total number of characters that will be present in the coupon.
Range of length
- Min: 1
- Max: 128
If length is not passed then default value of 6 is considered.
Coupon with prefix
To generate a coupon with a given prefix we pass the following option to the generate
method.
const myCoupon = coupon.generate({
prefix: 'SUPER'
});
The above code will generate coupon with prefix 'SUPER'. Default lenght of the coupon is 6. So, we will get coupon like the following.
SUPERAAAAAA
Note! Prefix characters are not counted.
If we want to generate coupon of length 3 with prefix 'SUPER' then our option will look like the following.
const myCoupon = coupon.generate({
length: 3,
prefix: 'SUPER'
});
We will get coupon like the following SUPERAAA
.
Coupon with suffix
To create coupon with suffix pass the following option.
const myCoupon = coupon.generate({
length: 3,
suffix: 'AWESOME'
});
The above code will generate coupon like the following ZZZAWESOME
.
Note! Characters of the suffix is not counted. If length is not specified then default value of 6 is considered as the length.
Coupon with prefix and suffix
To create coupon with prefix and suffix pass the following option.
const myCoupon = coupon.generate({
length: 6,
prefix: 'SUPER',
suffix: 'AWESOME'
});
The above code will generate coupon like the following SUPERZZZZZZAWESOME
.
Note! The characters of the prefix and suffix is not considered. If length is not specified then default value of 6 is considered.
Coupon with built in character set
To create coupon code with built in character set pass the following option.
const myCoupon = coupon.generate({
characterSet: {
builtIn: ['charSetName']
}
});
Where, charSetName
is any of the following
CHARSET_ALPHA
-- consists of uppercase alphabet charactersA-Z
CHARSET_ALPHA_LOWER
-- consists of lowercase alphabet charactersa-z
CHARSET_DIGIT
-- consists of digits0-9
CHARSET_ALNUM
-- consists of uppercase alphabetA-Z
, lowercase alphabeta-z
and digit0-9
CHARSET_BINARY
-- consists of characters01
CHARSET_OCTAL
-- consists of characters01234567
CHARSET_HEX
-- consists of characters0-9
andA-F
CHARSET_HEX_LOWER
-- consists of characters0-9
anda-f
Example: If we want uppercase and digit we can pass the following.
const myCoupon = coupon.generate({
characterSet: {
builtIn: ['CHARSET_ALPHA', 'CHARSET_DIGIT']
}
});
Reference:
Coupon with custom characterSet
To use custom characters to generate coupons pass the following option.
const myCoupon = coupon.generate({
characterSet: {
custom: ['customChar']
}
});
Where, customChar
is any custom characters that you wish to use.
Example: To use ABC
, xyz
and 01234
in coupon pass the following.
const myCoupon = coupon.generate({
characterSet: {
custom: ['ABC', 'xyz', '01234']
}
});
Coupons using built in and custom character set
Example: Following option will use digit 0-9
and alphabet ABC
.
const myCoupon = coupon.generate({
characterSet: {
builtIn: ['CHARSET_DIGIT'],
custom: ['ABC']
}
});
Generate multiple unique coupons
Pass the following to generate multiple unqiue coupons.
const myCoupons = coupon.generate({
numberOfCoupons: number
});
The above code will return an array of coupons.
Where, number
represents the total number of unique coupons to generate.
Range of numberOfCoupons
- Min 1
- Max 100000
Example:
Following code will generate 3 unique coupons of length 8 using builtIn CHARSET_ALPHA
and CHARSET_DIGIT
option.
const myCoupons = coupon.generate({
length: 8,
numberOfCoupons: 3,
characterSet: {
builtIn: ['CHARSET_ALPHA', 'CHARSET_DIGIT']
}
});
Sample output:
['95TMY9JV', 'RZU6ZL0K', '1Q19N019']
Reference:
Omit characters
To omit characters from the generated coupon code we pass the following option.
const myCoupons = coupon.generate({
omitCharacters: ['charToOmit']
});
Where, omitCharacters
is the field that will help in omitting the characters.
charToOmit
is a string of characters to omit from the generated coupon codes.
Example:
const myCoupons = coupon.generate({
omitCharacters: ['ABC', 'XYZ']
});
The above code will generate coupons that will omit characters A
, B
, C
, X
, Y
and Z
.
Format coupons
We can format the coupons that are generated by the engine in two ways.
String format rule
This is the quick and easy way to format the coupon.
Use x
's for coupon characters and -
's to separate them into groups.
Example:
In the following setup we want to generate total 3
coupons.
Each coupons will be formatted like xxxx-xxxx-xxxx
where, x
's represents the coupon character
and -
's represent the separator. Length of each coupon code is 12.
Note! Total number of characters in the coupon code must be equal to the number of x
's in the format.
const myCoupons = coupon.generate({
format: 'xxxx-xxxx-xxxx',
length: 12,
numberOfCoupons: 3
});
Sample output:
['OHGP-DTMG-HINR', 'DKXN-ALFH-LOQX', 'TAFK-GVXJ-WMPR']
Object format rule
This gives us more formatting options and looks like the following.
{
separators: ['chars', 'chars', ...],
groups: [size, size, ...]
}
Where, separators
are the ones separating the coupon characters into groups.
And groups
represents the size of each group.
chars
represents the separator characters. It can be a single character or multiple characters like '-' or '##'.
size
represents the size of a group. It is an integer value greater than 0.
Note! Total number of elements in the separators
array must be one less than the total number of elements
in the groups
array.
Example:
In the following example we are generating 3
coupons each having 12
characters.
We are formatting the coupons into 4 groups
having 2, 4, 4, and 2 characters in that order.
And we are separating the
- 1st and 2nd group with
-
- 2nd and 3rd group with
~
- 3rd and 4th group with
-
const myCoupons = coupon.generate({
format: {
separators: ['-', '~', '-'],
groups: [2, 4, 4, 2]
},
length: 12,
numberOfCoupons: 3
});
['OH-GPDT~MGHI-NR', 'DK-XBCL~FHLO-QX', 'TA-FKGV~XJWM-PR']
Format coupon with prefix and suffix
If we have prefix and suffix then we have to consider the total number of characters in them too while setting the format field.
String format rule and prefix-suffix combo
Lets say we want to generate a coupon having 6 characters and also add prefix QWERT
and suffix ZXCVB
to it.
So, our configuration will look something like the following.
const myCoupon = coupon.generate({
length: 6,
prefix: 'QWERT',
suffix: 'ZXCVB'
});
On executing this we will get coupon code like
QWERTOWLZJHZXCVB
Note! Total number of characters in the generated coupon is 5+6+5
.
QWERT = 5 characters (prefix)
OWLZJH = 6 characters (generated coupon, as length is set to 6)
ZXCVB = 5 characters (suffix)
------------------------------
Total = 16 characters (coupon with prefix and suffix)
To format the above generated coupon with prefix and suffix we have to consider total 16 x
's.
In the following configuration we are formatting the coupon with prefix and suffix.
const myCoupon = coupon.generate({
length: 6,
prefix: 'QWERT',
suffix: 'ZXCVB',
format: 'xxxx-xxxx-xxxx-xxxx'
});
On executing this we will get coupon code like
QWER-TOWL-ZJHZ-XCVB
Object format rule and prefix-suffix combo
If we want to generate a coupon having 6 characters and attach prefix QWERT
and suffix ZXCVB
then our configuration
will look like the following.
const myCoupon = coupon.generate({
length: 6,
prefix: 'QWERT',
suffix: 'ZXCVB',
format: {
separators: ['-', '~', '-'],
groups: [2, 6, 6, 2]
}
});
We are formatting the coupon into 4 groups
having 2, 6, 6, and 2 characters in that order.
And we are separating the
- 1st and 2nd group with
-
- 2nd and 3rd group with
~
- 3rd and 4th group with
-
And we can add the following format
configuration to get formatted coupon.
On executing this we will get coupon code like
QW-ERTOWL~ZJHZXC-VB
Possible number of coupons
This section estimates the possible number of coupons that can be generated using different combinations of characters.
|Character Set |Characters |Total Characters |Coupon Length |Total possibility |Coupon Length |Total possibility |Coupon Length |Total possibility | |--------------------|--------------|--------------------|--------------|-----------------:|--------------|-----------------:|--------------|-----------------:| |CHARSET_ALPHA |A-Z |26 |6 |308915776 |8 |208827064576 |12 |9.5428957e+16 | |CHARSET_ALPHA_LOWER |a-z |26 |6 |308915776 |8 |208827064576 |12 |9.5428957e+16 | |CHARSET_DIGIT |0-9 |10 |6 |1000000 |8 |100000000 |12 |1e+12 | |CHARSET_ALNUM |A-Z, a-z, 0-9 |62 |6 |56800235584 |8 |2.1834011e+14 |12 |3.2262668e+21 | |CHARSET_BINARY |0-1 |2 |6 |64 |8 |256 |12 |4096 | |CHARSET_OCTAL |0-7 |8 |6 |262144 |8 |16777216 |12 |68719476736 | |CHARSET_HEX |0-9, A-F |16 |6 |16777216 |8 |4294967296 |12 |2.8147498e+14 | |CHARSET_HEX_LOWER |0-9, a-f |16 |6 |16777216 |8 |4294967296 |12 |2.8147498e+14 |
Points to note!
- Repetition of characters considered in the above computation.
- Prefix and Suffix not considered in the above computaion.
- Omit characters is not set in the above computation.
- Different mix of character sets can be used to change the total number of possible coupons that can be generated.
- Speed and generation of coupons will also depend on the hardware used.
Storage size
In this section we estimate the rough storage size based on the coupon size and number of coupons generated.
Assumption:
- Using UTF8 characters and each character taking up 1 byte storage.
|Total Characters |Number of coupons |Size (MB) |Size (GB) | |----------------:|---------------------:|-----------------:|-----------------:| |6 |1000 |0.006 |0.000006 | |6 |10000 |0.060 |0.000060 | |6 |100000 |0.600 |0.000600 | |6 |1000000 |6.000 |0.006000 | |6 |10000000 |60.000 |0.060000 | |6 |100000000 |600.000 |0.600000 | |6 |1000000000 |6000.000 |6.000000 |
|Total Characters |Number of coupons |Size (MB) |Size (GB) | |----------------:|---------------------:|-----------------:|-----------------:| |8 |1000 |0.008 |0.000008 | |8 |10000 |0.080 |0.000080 | |8 |100000 |0.800 |0.000800 | |8 |1000000 |8.000 |0.008000 | |8 |10000000 |80.000 |0.080000 | |8 |100000000 |800.000 |0.800000 | |8 |1000000000 |8000.000 |8.000000 |
|Total Characters |Number of coupons |Size (MB) |Size (GB) | |----------------:|---------------------:|-----------------:|-----------------:| |12 |1000 |0.012 |0.000012 | |12 |10000 |0.120 |0.000120 | |12 |100000 |1.200 |0.001200 | |12 |1000000 |12.000 |0.012000 | |12 |10000000 |120.000 |0.120000 | |12 |100000000 |1200.000 |1.200000 | |12 |1000000000 |12000.000 |12.000000 |
|Total Characters |Number of coupons |Size (MB) |Size (GB) | |----------------:|---------------------:|-----------------:|-----------------:| |16 |1000 |0.016 |0.000016 | |16 |10000 |0.160 |0.000160 | |16 |100000 |1.600 |0.001600 | |16 |1000000 |16.000 |0.016000 | |16 |10000000 |160.000 |0.160000 | |16 |100000000 |1600.000 |1.600000 | |16 |1000000000 |16000.000 |16.000000 |
Older version
CommonJS version - check v0.9.4
License
It's free :smiley:
MIT License Copyright (c) 2020 Yusuf Shakeel
Donate
Feeling generous :smiley: Donate via PayPal