util.keys v0.0.22

util.keys

Maintains a set of unique keys generated for a react component

Installation

This module uses yarn to manage dependencies and run scripts for development.

To install as an application dependency:

$ yarn add --dev util.keys

To build the app and run all tests:

$ yarn run all

Overview

The use case for this module is to generate unique keys used by a React control that will be in an array. This associates a UUID to each index of the array. Separate instances of the same control can then use their index positions to associated a unique id that will not collide between instances. This is to avoid using the array index as the unique key for a control.

Usage

Basic

import * as React from 'react';
import {Keys} from 'util.keys';

export class Foo extends React.Component<P, S> {
	private _keys = new Keys();

	constructor(props: any) {
		super(props);
	}

	render() {
		let controls = [];
		for (let i=0; i<20; i++) {
			controls.push(
				<div key={this._keys.at(i)}>foo</div>
			);
		}
		return (
			<div>
			{controls}
			</div>
		);
	}
}

When Foo is rendered the key values associated with each instance in controls is a unique UUID instead of the index of the array. On each re-render of the controls array the index values retrieved by this._keys.at(i) resolves back to the same UUID for that instance. If one were to create another instance of Foo then it would have its own set of UUID values for each index of its controls array. This ensures unique keys across instances.

The index values given to .at(idx) do not need to be sequential. They are of type KeyIndex, which is either a number or string. Any number or string can be used to retrieve a key. Numbers are used directly, where a string index is converted to a hash first. On retrieval the idx/uuid are paired together for the life of the instance. It is not a good idea to mix numbers and strings with the .at() as it could lead to collisions in the key object if an index selected matches what is generated by a hash.

A convenience method is also provided to retrieve the next() id string available. It assumes a start of 0 if no previous index was given.

Testing

The same basic method is used during testing. However, when using snapshot testing it is not desirable for the key value to randomly change with each test run. The control can be configured to produce a stable, predicatble key when the testing flag is set.

import * as React from 'react';
import {Keys} from 'util.keys';

export class Foo extends React.Component<P, S> {
	private _keys = new Keys({testing: true, testingPrefix: 't'});

	constructor(props: any) {
		super(props);
	}

	render() {
		let controls = [];
		for (let i=0; i<20; i++) {
			controls.push(
				<div key={this._keys.at(i)}>foo</div>
			);
		}
		return (
			<div>
			{controls}
			</div>
		);
	}
}

Each of the component key values will be produced in numeric order starting from 0. A string can also be prepended to each key. In this example each key has the string "t" prepended, so the values are "t0, t1, t2...".

API

• Key()
• .at(number|string) . .contains(number|string)
• .next()

The Key class contructor takes an options object for configuration parameters. It has the following options:

• cacheSize {number} (25) - the number of items in the array cache. The class will preload 25 items by default.
• testing {boolean} (false) - when this option is set the id values returned are an echo of the requested index. This is used for testing (as snapshot testing will not work with this class).
• testingPrefix: {string} ('') - when the testing option is set this prefix will be prepended to the index string used for testing. By default this is an empty string.