# util.keys

> Maintains a set of unique keys generated for a react component

Latest version **0.0.22** (published 2019-12-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install util.keys
pnpm add util.keys
yarn add util.keys
bun add util.keys
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.22 |
| Published | 2019-12-15 |
| First published | 2017-08-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=7.x |
| Dependencies | 3 |
| Unpacked size | 24.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | jmquigley |
| Maintainers | jmquigley |

## Links

- npm: https://www.npmjs.com/package/util.keys
- Repository: https://github.com/jmquigley/util.keys
- Homepage: https://github.com/jmquigley/util.keys#readme
- Issues: https://github.com/jmquigley/util.keys/issues
- npm.io page: https://npm.io/package/util.keys

## Dependencies (3)

- [util.string](https://npm.io/package/util.string.md) ^0.0.36
- [util.toolbox](https://npm.io/package/util.toolbox.md) ^0.0.86
- [util.constants](https://npm.io/package/util.constants.md) ^0.0.30

## Recent versions

- 0.0.22 (latest) — 2019-12-15
- 0.0.21 — 2019-06-06
- 0.0.20 — 2019-03-13
- 0.0.19 — 2019-03-08
- 0.0.18 — 2019-03-01
- 0.0.17 — 2019-03-01
- 0.0.16 — 2019-02-18
- 0.0.15 — 2019-01-08
- 0.0.14 — 2018-04-25
- 0.0.13 — 2018-04-19
- 0.0.12 — 2018-01-18
- 0.0.11 — 2017-12-03
- 0.0.10 — 2017-12-03
- 0.0.9 — 2017-11-18
- 0.0.8 — 2017-10-04
- … 7 more at https://npm.io/package/util.keys/versions

## README

# util.keys

> Maintains a set of unique keys generated for a react component

[![build](https://github.com/jmquigley/util.keys/workflows/build/badge.svg)](https://github.com/jmquigley/util.keys/actions)
[![analysis](https://img.shields.io/badge/analysis-tslint-9cf.svg)](https://palantir.github.io/tslint/)
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
[![testing](https://img.shields.io/badge/testing-jest-blue.svg)](https://facebook.github.io/jest/)
[![NPM](https://img.shields.io/npm/v/util.keys.svg)](https://www.npmjs.com/package/util.keys)


## Installation

This module uses [yarn](https://yarnpkg.com/en/) 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

```javascript
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](http://www.cse.yorku.ca/~oz/hash.html) 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.

```javascript
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()](docs/index.md#Keys)
- [.at(number|string)](docs/index.md#Keys+at)
. [.contains(number|string)](docs/index.md#Keys+contains)
- [.next()](docs/index.md#Keys+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.

---
_Source: https://npm.io/package/util.keys · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._