# @allmaps/id

> IDs for Allmaps

Latest version **1.0.0-beta.39** (published 2026-09-22) · ISC license · 0 weekly downloads

## Install

```sh
npm install @allmaps/id
pnpm add @allmaps/id
yarn add @allmaps/id
bun add @allmaps/id
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 1.0.0-beta.39 |
| Published | 2026-09-22 |
| First published | 2021-04-06 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | ESM |
| Node | >=v19.0.0 |
| Dependencies | 0 |
| Unpacked size | 16.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 143 |
| Author | Bert Spaan |
| Maintainers | bertspaan |
| Keywords | allmaps, id, identifier, checksum |

## Links

- npm: https://www.npmjs.com/package/@allmaps/id
- Repository: https://github.com/allmaps/allmaps
- Homepage: https://allmaps.org
- Issues: https://github.com/allmaps/id/issues
- npm.io page: https://npm.io/package/@allmaps/id

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 1.0.0-beta.39 (latest) — 2026-09-22
- 1.0.0-beta.33 (beta) — 2025-05-22
- 1.0.0-beta.38 — 2026-05-28
- 1.0.0-beta.37 — 2025-11-27
- 1.0.0-beta.36 — 2025-11-10
- 1.0.0-beta.35 — 2025-07-09
- 1.0.0-beta.34 — 2025-07-07
- 1.0.0-beta.32 — 2025-03-12
- 1.0.0-beta.30 — 2024-10-31
- 1.0.0-beta.29 — 2024-08-20
- 1.0.0-beta.28 — 2024-08-16
- 1.0.0-beta.27 — 2024-05-29
- 1.0.0-beta.26 — 2024-03-09
- 1.0.0-beta.23 — 2024-02-25
- 1.0.0-beta.22 — 2024-02-09
- … 33 more at https://npm.io/package/@allmaps/id/versions

## README

# @allmaps/id

Uses the [SHA-1](https://en.wikipedia.org/wiki/SHA-1) algorithm to generate IDs from strings, random IDs from UUIDs and checksums from JSON objects.

Allmaps uses this module to create IDs from IIIF URIs. For example:

* Given the following manifest URL: https://digital.zlb.de/viewer/api/v1/records/34231682/manifest/,
* The output of the [`generateId`](#generateid) function will be: `6f5a7b547c8f6fbe`,
* We can use this ID to lookup the [Georeference Annotation](https://iiif.io/api/extension/georef/) for the georeferenced maps in this manifest using Allmaps API:
  https://annotations.allmaps.org/manifests/6f5a7b547c8f6fbe.

To see @allmaps/id in action, view this [Observable notebook](https://observablehq.com/@allmaps/the-allmaps-id-module).

## Usage

This is an ESM-only module that works in browsers, Node.js, and Cloudflare Workers.

There are two variants:

* **Async** (default) — uses [`SubtleCrypto.digest()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest) and [`Crypto.randomUUID()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID). Works everywhere.
* **Sync** (`@allmaps/id/sync`) — pure-JS SHA-1 implementation with no external dependencies. Returns values synchronously. Useful when an async context is not available (e.g. inside Svelte `$derived`).

Both variants produce identical output.

### Async (default)

```js
import { generateId } from '@allmaps/id'

const url = 'https://digital.zlb.de/viewer/api/v1/records/34231682/manifest/'
const id = await generateId(url)
// id = '6f5a7b547c8f6fbe'
```

### Sync

```js
import { generateId, generateChecksum } from '@allmaps/id/sync'

const url = 'https://digital.zlb.de/viewer/api/v1/records/34231682/manifest/'
const id = generateId(url)
// id = '6f5a7b547c8f6fbe'
```

### Browser (via CDN)

```html
<script type="module">
  import { generateId } from 'https://esm.run/@allmaps/id'

  const url =
    'https://orka.bibliothek.uni-kassel.de/viewer/rest/iiif/manifests/1535113582549/manifest/'
  const id = await generateId(url)
  console.log(id)
</script>
```

## CLI

Generating Allmaps IDs is also possible using the [Allmaps CLI](https://github.com/allmaps/allmaps/tree/main/apps/cli).

For example:

```sh
echo https://digital.zlb.de/viewer/api/v1/records/34231682/manifest/ | allmaps id
```

## License

MIT

## API

### `generateChecksum(obj, length)`

Generates a checksum of a JSON object.

###### Parameters

* `obj` (`unknown`)
  * JSON object.
* `length` (`number | undefined`)
  * Length of returned hash. The maximum length of the hash is 40 characters.

###### Returns

First `length` characters of the SHA-1 hash of sorted and serialized version of `obj` (`Promise<string>`).

### `generateId(str, length)`

Generates an ID from a string using the SHA-1 algorithm. Given the same input, the ID will always be the same.

###### Parameters

* `str` (`string`)
  * Input string
* `length` (`number | undefined`)
  * Length of returned hash. The maximum length of the hash is 40 characters. The default length is 16.

###### Returns

First `length` characters of the SHA-1 hash of `str` (`Promise<string>`).

### `generateRandomId(length)`

Generates a random ID.

###### Parameters

* `length` (`number | undefined`)
  * Length of returned hash. The maximum length of the hash is 40 characters.

###### Returns

First `length` characters of the SHA-1 hash of a random UUID (`Promise<string>`).

### `generateChecksum(obj, length)`

Generates a checksum of a JSON object.

###### Parameters

* `obj` (`unknown`)
  * JSON object.
* `length` (`number | undefined`)
  * Length of returned hash. The maximum length of the hash is 40 characters.

###### Returns

First `length` characters of the SHA-1 hash of sorted and serialized version of `obj` (`string`).

### `generateId(str, length)`

Generates an ID from a string using the SHA-1 algorithm. Given the same input, the ID will always be the same.

###### Parameters

* `str` (`string`)
  * Input string
* `length` (`number | undefined`)
  * Length of returned hash. The maximum length of the hash is 40 characters. The default length is 16.

###### Returns

First `length` characters of the SHA-1 hash of `str` (`string`).

### `generateRandomId(length)`

Generates a random ID.

###### Parameters

* `length` (`number | undefined`)
  * Length of returned hash. The maximum length of the hash is 40 characters.

###### Returns

First `length` characters of the SHA-1 hash of a random UUID (`string`).

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