unique-sequence

Generate a sequence of short strings unique within their scope.

The generated strings are as short as possible.

Unlike uuid they are not universally unique. However a generator does not repeat a sequence, making strings unique within the scope of a generator instance.

This utility is built using Node.js.

Introduction

This library was written to generate short property names for JavaScript objects.

uuid is one way of generating property names which would make an object look like:

1{
2  '2bdff0e2-9c4f-4b12-8669-7dac3dbf3203': 1,
3  '7b5c615c-03b2-4bb0-b8ff-995cebeed679': true
4}

In the above, property names 2bdff0e2-9c4f-4b12-8669-7dac3dbf3203, 7b5c615c-03b2-4bb0-b8ff-995cebeed679 are relatively long.

Instead, if you want to generate a few and very short names such as a, b then this library can help.

Quick example

1const { generatorCustom } = require('unique-sequence');
2
3// A string generator using 2 characters: 'a' and 'b':
4const gen = generatorCustom(['a', 'b']);
5console.log(gen.next().value); // a
6console.log(gen.next().value); // b
7console.log(gen.next().value); // ba
8console.log(gen.next().value); // bb
9console.log(gen.next().value); // baa
10
11// and so on...

How it works

It is similar to a sequence of integers.

For instance, below is a sequence generated using decimal digits 0 to 9:

0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
10, 11, 12, 13, 14, 15, 16, 17, 18, 19,
20, 21, 22, 23, 24, 25, 26, 27, 28, 29,
30

Below is a sequence using the list of latin alphabets a to j:

 a,  b,  c,  d,  e,  f,  g,  h,  i,  j,
ba, bb, bc, bd, be, bf, bg, bh, bi, bj,
ca, cb, cc, cd, ce, cf, cg, ch, ci, cj,
da

In a similar manner, this library generates sequences, using a specified list of characters (or strings).

Generators available

1. generatorCustom
2. generatorAlphaUpper
3. generatorAlphaLower
4. generatorAlphaNumUpper
5. generatorAlphaNumLower
6. generatorNum

Getting started

Install this library

1npm install unique-sequence

Example program

1const {
2  generatorCustom,
3  generatorNum,
4  generatorAlphaUpper,
5  generatorAlphaLower,
6  generatorAlphaNumUpper,
7  generatorAlphaNumLower,
8} = require('unique-sequence');
9
10
11/* Generate a sequence using letters 'a' to 'z' */
12const gen = generatorAlphaLower();
13console.log(gen.next().value); // a
14console.log(gen.next().value); // b
15console.log(gen.next().value); // c
16console.log(gen.next().value); // d
17console.log(gen.next().value); // e
18console.log(gen.next().value); // f
19console.log(gen.next().value); // g
20console.log(gen.next().value); // h
21console.log(gen.next().value); // i
22console.log(gen.next().value); // j
23console.log(gen.next().value); // k
24console.log(gen.next().value); // l
25console.log(gen.next().value); // m
26console.log(gen.next().value); // n
27console.log(gen.next().value); // o
28console.log(gen.next().value); // p
29console.log(gen.next().value); // q
30console.log(gen.next().value); // r
31console.log(gen.next().value); // s
32console.log(gen.next().value); // t
33console.log(gen.next().value); // u
34console.log(gen.next().value); // v
35console.log(gen.next().value); // w
36console.log(gen.next().value); // x
37console.log(gen.next().value); // y
38console.log(gen.next().value); // z
39console.log(gen.next().value); // ba
40console.log(gen.next().value); // bb
41console.log(gen.next().value); // bc
42console.log(gen.next().value); // bd
43console.log(gen.next().value); // be
44console.log(gen.next().value); // bf
45// and so on...
46
47
48/* Lets generate a sequence using two elements 'a' and 'b' */
49const list = ['a', 'b'];
50
51// NOTE: The length of the list should be <=36 and >= 2
52
53const gen2 = generatorCustom(list);
54console.log(gen2.next().value); // a
55console.log(gen2.next().value); // b
56console.log(gen2.next().value); // ba
57console.log(gen2.next().value); // bb
58console.log(gen2.next().value); // baa
59console.log(gen2.next().value); // bab
60console.log(gen2.next().value); // bba
61console.log(gen2.next().value); // bbb
62console.log(gen2.next().value); // baaa
63
64/* Using three elements 'x', 'y', 'z' */
65const gen3 = generatorCustom(['x', 'y', 'z']);
66console.log(gen3.next().value); // x
67console.log(gen3.next().value); // y
68console.log(gen3.next().value); // z
69console.log(gen3.next().value); // yx
70console.log(gen3.next().value); // yy
71console.log(gen3.next().value); // yz
72console.log(gen3.next().value); // zx
73console.log(gen3.next().value); // zy
74console.log(gen3.next().value); // zz
75console.log(gen3.next().value); // yxx
76
77/* Let us make a helper to iterate over the sequence generator  */
78function times(gen, count = 64) {
79  const arr = [];
80  for (let i = 0; i < count; i++) {
81    arr.push(gen.next().value);
82  }
83  return arr;
84}
85
86// Generate 10 strings, just like our previous example.
87console.log(times(generatorCustom(['x', 'y', 'z']), 10));
88// [
89//   'x',   'y',  'z',
90//   'yx',  'yy', 'yz',
91//   'zx',  'zy', 'zz',
92//   'yxx'
93// ]
94
95/* Lets generate 64 stings using upercase latin alphabets */
96console.log(times(generatorAlphaUpper())); // 64 is the default
97// [
98//   'A',  'B',  'C',  'D',  'E',  'F',  'G',  'H',
99//   'I',  'J',  'K',  'L',  'M',  'N',  'O',  'P',
100//   'Q',  'R',  'S',  'T',  'U',  'V',  'W',  'X',
101//   'Y',  'Z',  'BA', 'BB', 'BC', 'BD', 'BE', 'BF',
102//   'BG', 'BH', 'BI', 'BJ', 'BK', 'BL', 'BM', 'BN',
103//   'BO', 'BP', 'BQ', 'BR', 'BS', 'BT', 'BU', 'BV',
104//   'BW', 'BX', 'BY', 'BZ', 'CA', 'CB', 'CC', 'CD',
105//   'CE', 'CF', 'CG', 'CH', 'CI', 'CJ', 'CK', 'CL'
106// ]
107
108/* There's lower case too */
109console.log(times(generatorAlphaLower()));
110// [
111//   'a',  'b',  'c',  'd',  'e',  'f',  'g',  'h',
112//   'i',  'j',  'k',  'l',  'm',  'n',  'o',  'p',
113//   'q',  'r',  's',  't',  'u',  'v',  'w',  'x',
114//   'y',  'z',  'ba', 'bb', 'bc', 'bd', 'be', 'bf',
115//   'bg', 'bh', 'bi', 'bj', 'bk', 'bl', 'bm', 'bn',
116//   'bo', 'bp', 'bq', 'br', 'bs', 'bt', 'bu', 'bv',
117//   'bw', 'bx', 'by', 'bz', 'ca', 'cb', 'cc', 'cd',
118//   'ce', 'cf', 'cg', 'ch', 'ci', 'cj', 'ck', 'cl'
119// ]
120
121/* Alpha Numeric too */
122console.log(times(generatorAlphaNumLower()));
123// [
124//   '0',  '1',  '2',  '3',  '4',  '5',  '6',  '7',
125//   '8',  '9',  'a',  'b',  'c',  'd',  'e',  'f',
126//   'g',  'h',  'i',  'j',  'k',  'l',  'm',  'n',
127//   'o',  'p',  'q',  'r',  's',  't',  'u',  'v',
128//   'w',  'x',  'y',  'z',  '10', '11', '12', '13',
129//   '14', '15', '16', '17', '18', '19', '1a', '1b',
130//   '1c', '1d', '1e', '1f', '1g', '1h', '1i', '1j',
131//   '1k', '1l', '1m', '1n', '1o', '1p', '1q', '1r'
132// ]
133
134/* Alpha Numeric in upper case */
135console.log(times(generatorAlphaNumUpper()));
136// [
137//   '0',  '1',  '2',  '3',  '4',  '5',  '6',  '7',
138//   '8',  '9',  'A',  'B',  'C',  'D',  'E',  'F',
139//   'G',  'H',  'I',  'J',  'K',  'L',  'M',  'N',
140//   'O',  'P',  'Q',  'R',  'S',  'T',  'U',  'V',
141//   'W',  'X',  'Y',  'Z',  '10', '11', '12', '13',
142//   '14', '15', '16', '17', '18', '19', '1A', '1B',
143//   '1C', '1D', '1E', '1F', '1G', '1H', '1I', '1J',
144//   '1K', '1L', '1M', '1N', '1O', '1P', '1Q', '1R'
145// ]
146
147/* For the sake of completion, use decimal digits */
148console.log(times(generatorNum()));
149// [
150//   '0',  '1',  '2',  '3',  '4',  '5',  '6',  '7',
151//   '8',  '9',  '10', '11', '12', '13', '14', '15',
152//   '16', '17', '18', '19', '20', '21', '22', '23',
153//   '24', '25', '26', '27', '28', '29', '30', '31',
154//   '32', '33', '34', '35', '36', '37', '38', '39',
155//   '40', '41', '42', '43', '44', '45', '46', '47',
156//   '48', '49', '50', '51', '52', '53', '54', '55',
157//   '56', '57', '58', '59', '60', '61', '62', '63'
158// ]
159
160/* Let's have some fun! */
161console.log(times(generatorCustom(['rat,', 'a', 'tat'])));
162// [
163//   'rat,',            'a',            'tat',
164//   'arat,',           'aa',           'atat',
165//   'tatrat,',         'tata',         'tattat',
166//   'arat,rat,',       'arat,a',       'arat,tat',
167//   'aarat,',          'aaa',          'aatat',
168//   'atatrat,',        'atata',        'atattat',
169//   'tatrat,rat,',     'tatrat,a',     'tatrat,tat',
170//   'tatarat,',        'tataa',        'tatatat',
171//   'tattatrat,',      'tattata',      'tattattat',
172//   'arat,rat,rat,',   'arat,rat,a',   'arat,rat,tat',
173//   'arat,arat,',      'arat,aa',      'arat,atat',
174//   'arat,tatrat,',    'arat,tata',    'arat,tattat',
175//   'aarat,rat,',      'aarat,a',      'aarat,tat',
176//   'aaarat,',         'aaaa',         'aaatat',
177//   'aatatrat,',       'aatata',       'aatattat',
178//   'atatrat,rat,',    'atatrat,a',    'atatrat,tat',
179//   'atatarat,',       'atataa',       'atatatat',
180//   'atattatrat,',     'atattata',     'atattattat',
181//   'tatrat,rat,rat,', 'tatrat,rat,a', 'tatrat,rat,tat',
182//   'tatrat,arat,',    'tatrat,aa',    'tatrat,atat',
183//   'tatrat,tatrat,',  'tatrat,tata',  'tatrat,tattat',
184//   'tatarat,rat,'
185// ]
186
187/* Lower case alphabets again, but this time specify the characters. */
188console.log(times(generatorCustom([
189  'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h',
190  'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p',
191  'q', 'r', 's', 't', 'u', 'v', 'w', 'x',
192  'y', 'z',
193])));
194
195// [
196//   'a',  'b',  'c',  'd',  'e',  'f',  'g',  'h',
197//   'i',  'j',  'k',  'l',  'm',  'n',  'o',  'p',
198//   'q',  'r',  's',  't',  'u',  'v',  'w',  'x',
199//   'y',  'z',  'ba', 'bb', 'bc', 'bd', 'be', 'bf',
200//   'bg', 'bh', 'bi', 'bj', 'bk', 'bl', 'bm', 'bn',
201//   'bo', 'bp', 'bq', 'br', 'bs', 'bt', 'bu', 'bv',
202//   'bw', 'bx', 'by', 'bz', 'ca', 'cb', 'cc', 'cd',
203//   'ce', 'cf', 'cg', 'ch', 'ci', 'cj', 'ck', 'cl'
204// ]
205
206/* Lastly, lets give a shot at using using upper and lower cases */
207try {
208console.log(times(generatorCustom([
209  'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h',
210  'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p',
211  'q', 'r', 's', 't', 'u', 'v', 'w', 'x',
212  'y', 'z',
213  'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H',
214  'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P',
215  'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X',
216  'Y', 'Z',
217])));
218} catch (e) {
219  console.error('error:', e.message);
220}
221// error: maximum list length is 36, got 52.
222
223// Thats because length must be 2 to 36.

Change log

version 1.0.4

2022-01-15

• Improved docs.

version 1.0.3

2022-01-15

• Improved docs.

version 1.0.0

2021-12-16

• Initial code to generate custom sequence, upper/lowercase, alphanum.

Note: Change log dates are yyyy-mm-dd.