npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@eatonfyi/ids

v1.1.0

Published

Generate, validate, and pretty-print a variety of IDs and hash formats.

Downloads

61

Readme

Eaton IDs

A wrapper/nomralizer around libraries for a bunch of different ID and hash formats I've had to deal with on my personal projects. Broadly, I'm less interested in efficiency here than giving myself a consistent set interface for using (and occasionally switching between) different ID and hash formats.

If you need something lightweight to deal with one particular ID type or generate hashes for a specific purpose, it'll be much simpler to pull in one of the specific libraries this one uses under the hood:

  • nanoid to generate fast, URL-safe unique IDs
  • ulid to generate and parse ULIDs (might replace with UUIDv7)
  • uuid to generate UUIDv1-UUIDv7
  • uuid25 to parse and format assorted representations of UUID data
  • fnv1a to generate quick, variable-length hashes of strings.
  • gtin to validate and parse GTIN, UPC, EAN, etc.
  • isbn3 to validate, parse, and convert between ISBN10 and ISBN13

What's In Here

Everything is broken down into three kinds of things:

  • Generators are functions that spit out random IDs when called. They may support additional parameters to control the ID generation process; nanoid, for example, accepts optinoal length and custom alphabet properties but does fine without them.
  • Hashers accept some thing that a hash value is being generated for. They, too, may accept additional parameters to control the hash generation process but without the thing-to-be-hashed they're just an ID generator.
  • Helpers are a set of standard sub-properties to validate, format, and inspect already-created IDs and hashes. Some Generators and Hashers also support Helpers.
    • <helper>.extract(input: NotUndefined) returns an ID when given some messy input data, or undefined if an ID can't be found. This is intended as a tool for extracting valid IDs from potentially messy input, for example turning Amazon URLs into ASINs when possible.
    • <helper>.isValid(input: string) to validate input data, returning true or false.
    • <helper>.format(input: string, style?: string) to pretty-print the parsed ID in its canonical format. Some ID types support additional format types as a second parameter.
    • <helper>.minify(input: string) to output the shortest valid format of the ID, if available. A hyphenated North American ISBN-13 is collapsed to an unhyphenated ISBN-10 if possible, for example.
    • <helper>.inspect(input: string) to return the parsed information inside an ID format. At the very least, the isValid property of this information will be populated with a boolean. If the ID can be parsed, the formatted and minified properties will also be populated. Other formats add fun stuff like "is there a timestamp hidden in the first n bytes" and "is this ISBN for Japan or Europe" and so on.

Generators are only meant to create unique IDs given a set of input parameters. NanoID, ULID, and UUIDv1/v3/v5 are examples.

Hashers are meant to accept almost any input and generate some kind of easily-comparable representation on the other side. Nanohash and UUIDv5/v7 are examples.

Hashes

  • hash(input: NotUndefined) just wraps the object-hash library for convenience.
  • md5(), sha1(), sha256(), and sha512() are convenience wrappers for object-hash's algorithm-specific hashing options.
  • fnv1a(input: NotUndefined) uses the same objct-stringification mechanism as object-hash, but uses the fnv1a hashing algorithm to generate 32-1024 bytes of hash data and return it as a BigInt.
  • nanohash(input: any, size?: number, alphabet?: string) wraps the fnv1a hashing algorithm in nanoid's alphabet based encoding options. The default settings generate short (11-12 character) URL-friendly hashes that are reasonably collision-resistant.
  • picohash(input: NotUndefined) is a convenience wrapper for the 32-bit URL-safe nanohash options.

NanoIDs

  • nanoid(size?: number, alphabet?: string) wraps the nanoid library, which generates arbitrarily-sized, url-safe, collision-resistant IDs. Shorter than UUIDs by default, with options to control the dictionary of characters used and the final length of the ID.
  • alphabets is a useful list of potential character sets that can be used with nanoid and nanohash. URL Safe strings are the default for both, but options like 'Uppercase' and 'NoLookalikes' can be handy as well.

UUIDs

  • uuid() generates a random UUID4.
  • uuid(input: any) combines object-hash stringification with UUIDv5 hashing. If an explicit null value is given, the nil UUID is returned.
  • uuid.isValid(input: string) can be used to check an existing string vor UUID validity.
  • uuid.random() is a convenience wrapper for uuid.v4.
  • uuid.sortable() is a convenience wrapper for uuid.v7.
  • uuid.getDate() extracts the date component from a v1 or v7 UUID.
  • uuid.url() is a convenience wrapper for uuid.v5() that uses the official uuid.namespaces.url hashing namespace. It also ensures that URL-parsable strings and actual URL objects result in the same hash value.
  • uuid.setNamespace() can be used to set a custom namespace for UUIDv3/UUIDv5 generation; it must be a valid UUID.
  • uuid.namespaces provides convenience consts for the official URL and DNS namespaces; uuid.namespaces.fyi is the one I use by default.

ULIDs

  • ulid() generates a unique, creation-time-sortable identifier that's URL-safe and a touch shorter than a UUID. Uses the ulid library.

Some special ID formats

I do a lot of wrangling with my book and media collections; while they're neither hashes nor random IDs, ISBN and ASIN parsing/formatting is folded in here because I'm a huge nerd. Fun.

ISBNs

  • isbn(input: string) parses and returns detailed information about the internal structure of any valid ISBN; if valid, the isbn10 and isbn13 properties can be used to retrieve both permutations if available.
  • isbn.asIsbn13(input: string) is a useful shortcut, returning undefined if the ISBN is invalid, and expanding ISBN10s to the full 13 digits, in one step.

Amazon Product IDs

  • asin(input: string) returns the raw input if it's a plausibly-formatted Amazon product ID, and undefined if it isn't.
  • asin.isValid() and asin.isIsbn(input: string) functions are useful for explicit validation
  • asin.asUrl(input: string) returns a full Amazon product URL for the ID if it's valid.