Common tools (hereinafter referred to as **ct**) - a common JavaScript data structures and associated processing procedures package ([package repository](https://github.com/VyacheslavMishin/ct/tree/master)).
npm install @vyacheslav97/ctts
import {createIterableTransformer, transformToIterable} from '@vyacheslav97/ct';
`
createIterableTransformer is highly recommended for usage instead of transformToIterable to avoid redundant target iterable constructor referencing.
For example, lets inspect a createIterableTransformer application from uicsds.ts:
`ts
/**
* Creates Array to Map converter
* @param arrayItemTransformer Array item transformer, derives key-value pair from array item
*/
export function createArrayToMap(
arrayItemTransformer: SingleToPair,
) {
return createIterableTransformer>(Map, arrayItemTransformer);
}
`
createArrayToMap creates an Array to Map transformer. All such transformer needs to be utilized is an array item transform function, which converts an array item to key-value pair for Map constructor.
Here goes an createArrayToMap application example:
`ts
// Clarifies the rule how to transform array item to a key-value pair list
const shiftedArrayItemToMapItemTransformer: SingleToPair
= (number): [number, number] => [number, number + 1];
// Creates array to map converter with certain array item rule transformation
const arrayToMapShifted = createArrayToMap(shiftedArrayItemToMapItemTransformer);
arrayToMapShifted([1, 2, 3]) //--> {1 -> 2, 2 -> 3, 3 -> 4} - final Map object content
`
Remember, you are able to create your own custom iterable transformers!
Universal iterable converter (standard data structures, UICSDS)
UICSDS module consists of createIterableTransformer applications to built-in JavaScript iterable datastructures. uicsds.ts represents UICSDS module content.
UICSDS module members can be imported as follows:
`ts
import {createArrayToMap, createMapToSet} from '@vyacheslav97/ct';
`
$3
It's pretty easy to use:
- first, just import caught your eye transformer creator
- then specify source iterable transformation function
- finally create your iterable converter
Example:
`ts
// All needed type aliases for conversion laws can be imported as follows:
import {
SingleToPair,
SingleToSingle,
PairToSingle
} from "@vyacheslav97/ct";
// Map item to a character transformer
const keyValuePairConcatenatedTransformer: PairToSingle
= (pair) => pair.join('');
// Create transformer itself
const keyValuePairConcatenated = createMapToString(keyValuePairConcatenatedTransformer);
keyValuepairConcatenated(new Map([[1, 1], [2, 2]])); // results in '1122'
`
Graph abstract class
Graph abstract class implements directed graph abstraction with basic graph content manipulations: adding nodes, deleting nodes.
Graph node is represented via following generic interface:
`ts
interface GraphNodeInterface {
nodeId: string, // unic graph node identifier
// set of other graph nodes ids, from which boundaries are received
incomingBoundaries: Map,
// set of other graph nodes which receive boundaries from a given node
outgoingBoundaries: Map,
// Extra node data, may be ommited
nodeData?: NodeData,
}
`
Graph class itself implements next interface:
`ts
interface GraphInterface {
// base data structure containing all graph nodes
nodes: Map>,
getNode: (nodeId: string) => GraphNodeInterface | undefined,
getNodeData: (nodeId: string) => NodeData | undefined,
hasNode: (nodeId: string) => boolean,
addNode: (node: GraphNodeInterface) => void,
removeNode: (nodeId: string) => GraphNodeInterface | undefined,
flatten: (startNodeId: string) => Iterable>,
buildPath: (startNodeId: string, endNodeId: string) => GraphNodeInterface[] | undefined,
}
`
Some methods are not covered above:
- setFlattenProcedure - initializes flatten method via user defined leveling step function
- setPathFinderProcedure - initializes buildPath method via user defined pathfinder
- buildFlattenProcedure, buildPathFinder - are used for two previous method, it is highly recommended to avoid calling these methods
- clear - removes all nodes from a Graph instance (so nodes Map becomes empty)
$3
Import Graph class:
`ts
import {Graph} from '@vyacheslav97/ct';
`
#### Initialization
Graph can be initialized via its constructor if proper set of arguments is passed.
Graph constructor expects following arguments:
`ts
constructor(
sourceIterable?: Iterable<[string, GraphNodeInterface]>,
config?: GraphConfig,
)
`
Where GraphConfig
`ts
interface GraphConfig {
levelingStepFunction?: LevelingStepFunction,
pathFinder?: PathBuilder,
}
type LevelingStepFunction = (
currentNode: GraphNodeInterface,
sourceGraph: GraphInterface,
) => GraphNodeInterface | null;
type PathBuilder = (
startNode: GraphNodeInterface,
endNode: GraphNodeInterface,
sourceGraph: GraphInterface,
) => GraphNodeInterface[];
`
Graph constructor utilizes addNode method under the hood: all nodes from sourceIterable are added keeping their input order. Particularly, if some input node references to inexistent node or has some other wrong data, error will be thrown
BE ADVISED!!! Graph constructor, as well as Tree constructor, as well as both classes addNode methods mutate their arguments.
If no constructor arguments are specified, empty graph instance is created.
Soon graph instance was created, nodes can be added to it via addMethod:
`ts
/**
* Adds node to graph. Throws error if node of the same id already exists
* @param nodeToAdd node to add, GraphNodeInterface<NodeData>
*/
addNode(nodeToAdd: GraphNodeInterface)
`
addNode adds a node to graph instance and all specified within that node edges.
Any node of graph instance can be retrieved using getNode method:
`ts
/**
* Returns graph node of specified id, if graph has node with such id
* @param nodeId target node id, string
*/
getNode(nodeId: string)
`
To retrieve nodeData you can use method getNodeData, which expects target node id as an argument.
To check whether graph possesses a node, use hasNode method (expects node id as an argument).
To remove some specific node, use removeNode method:
`ts
/**
* Removes node of given id. Does nothing if wrong id is provided
* @param nodeId id of node to remove, string
*/
removeNode(nodeId: string)
`
If graph is needed to be flattened, use flatten method. It returns an iterable, which can be used to convert a graph instance into array.
To find path between two specific nodes of given graph, use buildPath method.
flatten and builtPath have own peculiarities: both can be overridden, but only flatten has default behavior - it returns nodes field values iterable if no custom flatten procedure is specified.
To override flatten procedure, use setFlattenProcedure method.
Example:
`ts
// Has to gain one node from another. If it turns impossible - returns null
const levelingStepFunction: LevelingStepFunction = ( // function for "linked list"
currentNode: GraphNodeInterface,
graph: GraphInterface,
) => {
const {
outgoingBoundaries,
} = currentNode;
const firstOutgoingBoundary = [...outgoingBoundaries]?.[0]?.[0];
return graph.getNode(firstOutgoingBoundary) || null;
};
const graph = new Graph();
graph.setFlattenProcedure(levelingStepFunction);
// then call [...graph.flatten('someStartNodeId')], for example, or use for ... of, or whatever
`
To initialize or override buildPath method, call setPathFinderProcedure method.
Example:
`ts
// Simple pathfinder for "linked list"
const pathFinder: PathBuilder = (
startNode: GraphNodeInterface,
endNode: GraphNodeInterface,
graph: GraphInterface,
) => {
let currentNode: GraphNodeInterface = startNode;
const result: GraphNodeInterface[] = [];
do {
result.push(currentNode);
currentNode = graph.getNode([...currentNode.outgoingBoundaries]?.[0]?.[0])!;
} while(result[result.length - 1]?.nodeId !== endNode.nodeId)
return result;
};
const graph = new Graph();
graph.setPathFinderProcedure(pathFinder);
// here you go, call graph.buildPath('startNodeId', 'endNodeId');
// BUT REMEMBER: invalid node ids (e.g. absent one) will trigger an error
`
buildPath call with no initialization triggers an error.
Tree abstract class
Import Tree class:
`ts
import {Tree} from '@vyacheslav97/ct';
`
Tree abstract class extends Graph abstract class. This extension brings in following mutations:
- addNode:
`ts
/**
* Adds node to a tree instance, avoiding loops generation
* @param nodeToAdd node data to add
*
* Throws error, if:
* - Has more than one incoming or outgoing boundary
* - First added node has parentNodeId
* - Node of the same nodeId already exists on a tree instance
* - Node has parentNodeId out of its incomingBoundaries or outgoingBoundaries
*/
addNode(nodeToAdd: GraphNodeInterface)
`
- removeNode:
`ts
/**
* Removes a node from a tree instance (and the node whole subtree by default)
* Doesn't remove a node if it doesn't exist on the tree instance
* @param nodeId id of node to remove
* @param deleteSubTree if true (by default) node and its subtree are removed
*/
removeNode(nodeId: string, deleteSubTree = true)
`
- rootNodeId added - it contains tree root node id
- nodeData field becomes mandatory (but remains extensible): it has to contain parentNodeId field for each tree node except root one
- clear method calls Graph class clear method and sets rootNodeId = '' (empty string)
- Tree constructor adds nodes using its addNode method
- Each leaf node now has isLeaf nodeData property, set to true. It is handled automatically, so no needs to mess with it manually.
Mutations history template class
MutationsHistory template class import:
`ts
import {MutationsHistory} from '@vyacheslav97/ct';
`
MutationsHistory implements changes history abstract mechanism. It is described via following interface:
`ts
interface MutationsHistoryInterface {
lastSavedChangeIndex: number,
commitedMutations: HistoryUnitType[],
canceledMutations: HistoryUnitType[],
getCurrentMutation: () => HistoryUnitType | undefined,
addMutation: (mutation: HistoryUnitType) => void,
cancelLastMutation: () => void,
restoreCanceledMutation: () => void,
saveCurrentMutation: () => void,
backToSavedMutation: () => void,
saveAndClear: () => void,
clearHistory: () => void,
}
`
$3
Data:
- commitedMutations stack - stack of committed changes
- canceledMutations stack - stack of canceled changes
- lastSavedChangeIndex - index of last saved change
Methods:
- getCurrentMutation - returns the most recent committed change
- addMutation - adds a fresh mutation to commitedMutations stack. Devastates filled canceledMutations stack
- cancelLastMutation - removes the most recent mutation from commitedMutations stack and places it in canceledMutations stack
- restoreCanceledMutation - if there are canceled mutations, then removes fresh mutation from canceledMutations stack and moves it to commitedMutations stack
- saveCurrentMutation - updates lastSavedChangeIndex with commitedMutations.length - 1
- backToSavedMutation - cancels or restores all mutations up to the last saved
- saveAndClear - saves the most recent commited mutation and demolishes the rest (canceled inclusive)
- clearHistory - clears history
A MutationsHistory instance can be created using predefined committed history list via MutationsHistory class constructor:
`ts
constructor(sourceIterable?: Iterable) {
this.commitedMutations = sourceIterable ? [...sourceIterable]: [];
this.canceledMutations = [];
this.lastSavedChangeIndex = this.commitedMutations.length - 1;
}
`
MutationsHistory is able to store whatever you plan it to: from changed objects itself to actions that mutate certain data structure. But a whole template, that rules history rules, remains the same.
ErrorWithData template class
ErrorWithData template class can be imported as follows:
`ts
import {
ErrorWithData,
} from '@vyacheslav97/ct';
`
This class implements interface:
`ts
export interface ErrorBaseData {
message: string;
}
export interface ErrorWithDataInterface extends Error {
errorData?: DataType;
}
`
It allows a user to provide an error some extra data of sophisticated shape
Except mentioned above, ErrorWithData reproduces built in JS Error class behaviour
Usage example
`ts
interface TestErrorData extends ErrorBaseData {
code: number;
}
const errorData: TestErrorData = { message: 'Test error', code: 404 };
const error = new ErrorWithData(errorData);
throw error;
`
Binary search procedure template
Binary search template procedure import:
`ts
import {
binarySearch,
buildBinarySearch,
} from '@vyacheslav97/ct';
`
NOTE: it is highly recommended to prefer buildBinarySearch over binarySearch.
binarySearch implements well-known binary search algorithm for array of arbitrary content. It receives:
- sourceList - list of data for binary search (list cotains data of the same arbitrary type)
- target - binary search target
- comparator - function that compares array elements and has a result described via following interface:
`ts
interface ComparatorResult {
equal?: boolean,
less?: boolean,
greater?: boolean,
}
`
binarySearch returns target index, if target does exist on given array or undefined otherwise.
buildBinarySearch creates binarySearch instance with a given comparator:
`ts
const numbersComparator = (x: number, y: number): ComparatorResult => ({
less: x < y,
greater: x > y,
equal: x === y,
});
const numericalBinarySearch = buildBinarySearch(numbersComparator);
numericalBinarySearch([], 5); // undefined
numericalBinarySearch([1, 2, 3, 4, 5], 2); // 1
`
Duplicates search procedure template
Duplicates search procedure template import:
`ts
import {
duplicatesSearcher,
buildDuplicatesSearcher,
} from '@vyacheslav97/ct';
`
duplicatesSearcher function looks for duplicates within a given array of data. It accepts following arguments:
- source – duplications source iterable
- valueExtractor – optional function, derives a primitive according which two values are considered as duplicates
- Returns Map, which keys are valueExtractor values, values are lists of DuplicateData:
`ts
interface DuplicateData {
duplicateIndex: number;
duplicateValue: T;
}
`
Note: duplicatesSearcher returns empty Map only if source iterable is empty, otherwise it has maximum size equal to source iterable values amount.
buildDuplicatesSearcher builds a duplicatesSearcher instance with a given valueExtractor:
`ts
interface SimpleObjectData {
value: string,
}
const valueExtractor = (data: SimpleObjectData) => data.value;
const numericalDuplicatesSearcher = buildDuplicatesSearcher();
numericalDuplicatesSearcher([1, 2, 3, 4, 5]);
export const objectDuplicatesSearcher = buildDuplicatesSearcher(valueExtractor);
objectDuplicatesSearcher([
{
value: 'a',
},
{
value: 'a',
},
{
value: 'c',
},
]);
`
Unique values search procedure template
Unique values search procedure template import:
`ts
import {
uniqueValuesSearcher,
createUniqueValuesSearcher,
} from '@vyacheslav97/ct';
`
uniqueValuesSearcher accepts a uniform array and filters unique values out of it. This function requires two arguments:
- sourceArray - source array to filter unique values out of it
- uniqueFeatureValueExtractor - a function, that derives a value of uniqueness feature (according to this value two objects are considered as identical)
It is recommended to use createUniqueValuesSearcher over uniqueValuesSearcher. createUniqueValuesSearcher creates an instance of uniqueValuesSearcher using a particular uniqueness feature value extractor function
isNumber
isNumber validator import:
`ts
import isNumber from '@vyacheslav97/ct';
`
isNumber represents a simple method to check whether its argument actually number or not. It based on two consequent test:
- Ensures, that typeof input argument is number
- Examines result of Number.isNaN call on input argument
Decimal integer RegExp
Regular expressions for decimal integers testing import:
`ts
import {
integerNumberRegex,
unsignedIntegerNumberRegex,
negativeIntegerNumberRegex,
} from '@vyacheslav97/ct';
`
All expressions are aimed to detangle whether a whole given string is an integer or not.
Particularly:
- integerNumberRegex checks, whether an input string has signed or unsigned integer number: string optionally starts with a single + or -, followed by digits sequence, which starts with any digits except 0, or single usingned 0
- unsignedIntegerNumberRegex almost copies integerNumberRegex, but start signs are not allowed
- negativeIntegerNumberRegex almost copies integerNumberRegex, but start sign must be -
Decimal float RegExp
Regular expressions for decimal floats testing import:
`ts
import {
floatNumberRegex,
unsignedFloatNumberRegex,
negativeFloatingPointNumberRegex,
} from '@vyacheslav97/ct';
`
All expressions are aimed to detangle whether a whole given string is a float number or not.
Particularly:
- floatNumberRegex checks, whether an input string has signed or unsigned float number: string optionally starts with a single + or -, followed by digits sequence, which first digit can't be 0, or single 0 with no sign. All this stuff is accompanied with optional single dot and that dot has optional digits sequence. So, following numbers are correct: 0, 0., 0.241253, -1.24, 3, -5, +12 .
- unsignedFloatNumberRegex resembles floatNumberRegex, but denies starting sign, positive or negative
- negativeFloatingPointNumberRegex mimics floatNumberRegex, but requires - as a starting sign
Exponential format number RegExp
Regular expression for number of exponential format testing import:
`ts
import {
exponentialNumberFormatRegex,
} from '@vyacheslav97/ct';
``