Skip to content

konfirm/node-alphabet

Repository files navigation

Alphabet

Release Tests

Immutable alphabet, usable in situations where a fixed set of unique characters is to be allowed and needs to be trusted to remain the exact same. The implementation provides a lot of functionality already provided by string values, with the added benefit that an Alphabet instance is guaranteed to contains only unique characters, and is validated for it only once.

As of version 3.0 Alphabet supports Unicode alphabets. If Unicode alphabets were used with prior versions, this may have lead to issues with the semantics of the various methods and even the length property.

Installation

@konfirm/alphabet is a scoped package, which means the scope must be provided for both installation and usage.

Using npm

$ npm install --save @konfirm/alphabet

Using yarn

$ yarn add @konfirm/alphabet

Updating to version 3.0

There are slight differences in how Alphabet works internally, most notable

No default export

The default export was removed, this means you should now explicitly state you want to import Alphabet from the package

// const Alphabet = require('@konfirm/alphabet');
const { Alphabet } = require('@konfirm/alphabet');

Unicode support

If Alphabet was used with multi-byte unicode characters (e.g. emoji), chances are you ran into various issues varying from duplicate characters errors to strange behavior regarding indexOf and charAt. If you have any workarounds in place for this, you should be able to removed those.

Usage

An Alphabet instance is guaranteed to have a unique set of characters, with a minimum of one character.

Creating an Alphabet instance

Create a new Alphabet instance using the characters you need. If you don't explicitly need multiple Alphabet instances handling the same characters (and their order), consider using the Alphabet.from method.

CommonJS (JavaScript)

const { Alphabet } = require('@konfirm/alphabet');

const hex = new Alphabet('abcdef0123456789');

ES Module (JavaScript)

import { Alphabet } from '@konfirm/alphabet';

const hex = new Alphabet('abcdef0123456789');

TypeScript

import { Alphabet } from '@konfirm/alphabet';

const hex: Alphabet = new Alphabet('abcdef0123456789');

Alphabet.from({string|object} input)

In order to be more memory efficient and open the possibility to directly compare instances, the static from method can be used to ensure a previously created instance is re-used if it's available.

CommonJS (JavaScript)

const { Alphabet } = require('@konfirm/alphabet');

const singleton = Alphabet.from('abc');
const proof = Alphabet.from('abc');

console.log(singleton === proof); //  true

const instance = new Alphabet('abc');

console.log(singleton === instance); //  false

ES Module (JavaScript)

import { Alphabet } from '@konfirm/alphabet';

const singleton = Alphabet.from('abc');
const proof = Alphabet.from('abc');

console.log(singleton === proof); //  true

const instance = new Alphabet('abc');

console.log(singleton === instance); //  false

TypeScript

import { Alphabet } from '@konfirm/alphabet';

const singleton: Alphabet = Alphabet.from('abc');
const proof: Alphabet = Alphabet.from('abc');

console.log(singleton === proof); //  true

const instance: Alphabet = new Alphabet('abc');

console.log(singleton === instance); //  false

Instance API

name purpose
characters The characters provided to the Alphabet during construction
length The number of characters
byteLength The number of bytes (unicode characters may be more than a single byte)
Alphabet(characters) Create a new Alphabet instance, if no characters are provided at all, the default (all characters a-zA-Z0-9) is used
charAt(index) The character at the specified index (undefined if the index is below 0 or above length)
charCodeAt(index) The character code at the specified index (undefined if the index is below 0 or above length)
codePointAt(index) The code point at the specified index (undefined if the index is below 0 or above length)
map(...index) Maps the provided indices to their characters, the indices will be wrapped to be within the Alphabet
indexOf(char) Find the index of the provided character, -1 if not found
slice([start [, end]]) Create a new alphabet (singleton) based on a slice of the current alphabet

Possible errors

An Alphabet requires its characters to be provided either as string or as object (with toString implemented), with a minimum length of one character. Furthermore all characters must be unique.

input error reason
'' InvalidInputError The input does not contain any characters
123 InvalidInputError The input is not a string
null InvalidInputError The input is not an stringifiable object
{} DuplicateCharacterError The string representation of {} is [Object object]
[] InvalidInputError The input is an array

The intended use to subclass the Alphabet and overriding the CHARACTERS getter method to indicate the supported character set.

The subclass (or Alphabet itself of course) can then be used in situations where the characters and their order matter and need a bit more testability than plain strings.

License

MIT License Copyright (c) 2019-2021 Rogier Spieker (Konfirm)

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.