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

isbn3

v1.2.4

Published

ISBN utils: parse, validate, format, audit

Downloads

13,786

Readme

isbn3

Node

An ISBN JavaScript Library.

Please note that this is a fork of isbn2, which was a fork of isbn package which was forked from the original isbnjs project on Google Code.

Ranges data are generated from isbn-international.org data.

Added features compared to isbn2:

  • recover common errors:
    • ignore bad hyphenization (ex: 978-1933988030)
  • modularizing and updating the code for ES6, in a class-less way.
  • improve performance (see benchmark)
  • Auto-update groups data every month

Demo

NPM

Auto-update groups data

Summary

Install

From the command line:

npm install isbn3

Then in your JS file:

const ISBN = require('isbn3')

Alternatively, you can call the ES5 browserified version of the module from an HTML file, which sets the module object on window.ISBN:

<script type="application/javascript" src="./node_modules/dist/isbn.js"></script>

See ./index.html or the live demo for an example.

Functions

parse

ISBN.parse('1-933988-03-7')
// => {
// source: '1-933988-03-7',
// isValid: true,
// isIsbn10: true,
// isIsbn13: false,
// group: '1',
// publisher: '933988',
// article: '03',
// check: '7',
// isbn13: '9781933988030',
// isbn13h: '978-1-933988-03-0',
// check10: '7',
// check13: '0',
// groupname: 'English language',
// isbn10: '1933988037',
// isbn10h: '1-933988-03-7'
// }

ISBN.parse('1933988037')
// => idem but with source === '1933988037'

ISBN.parse('978-4-87311-336-4')
// => {
//   source: '978-4-87311-336-4',
//   isValid: true,
//   isIsbn10: false,
//   isIsbn13: true,
//   prefix: '978',
//   group: '4',
//   publisher: '87311',
//   article: '336',
//   check: '4',
//   isbn13: '9784873113364',
//   isbn13h: '978-4-87311-336-4',
//   check10: '9',
//   check13: '4',
//   groupname: 'Japan',
//   isbn10: '4873113369',
//   isbn10h: '4-87311-336-9'
// }

ISBN.parse('9784873113364')
// => idem but with source === '9784873113364'

ISBN.parse('978-4873113364')
// => idem but with source === '978-4873113364'

ISBN.parse('979-10-96908-02-8')
// {
//   source: '979-10-96908-02-8',
//   isValid: true,
//   isIsbn10: false,
//   isIsbn13: true,
//   prefix: '979',
//   group: '10',
//   publisher: '96908',
//   article: '02',
//   check: '8',
//   isbn13: '9791096908028',
//   isbn13h: '979-10-96908-02-8',
//   check10: '6',
//   check13: '8',
//   groupname: 'France'
// }

ISBN.parse('not an isbn')
// => null

asIsbn13

ISBN.asIsbn13('4-87311-336-9')           // 9784873113364
ISBN.asIsbn13('4-87311-336-9', true)     // 978-4-87311-336-4

asIsbn10

ISBN.asIsbn10('978-4-87311-336-4')       // 4873113369
ISBN.asIsbn10('978-4-87311-336-4', true) // 4-87311-336-9

hyphenate

ISBN.hyphenate('9784873113364')          // 978-4-87311-336-4

audit

Get clues for possible mistake in an ISBN.

For instance, if in your data, a French edition has an ISBN-13 starting by 978-1-0, which would make it part of an English language groups, it could be that somewhere a prefix mistake was made and the ISBN actually starts by 979-10 (a French group). This is typically the case when an 979-prefix ISBN-13 was converted to an ISBN-10 (which is wrong as 979-prefixed ISBNs can't have ISBN-10), and then re-converted to an ISBN-13 with the 978 prefix. This is soooo wrong, but data is a dirty place I'm afraid.

ISBN.audit('9784873113364')
// {
//   "source": "9784873113364",
//   "validIsbn": true,
//   "groupname": "Japan",
//   "clues": []
// }

ISBN.audit('9781090648525')
// {
//   "source": "9781090648525",
//   "validIsbn": true,
//   "groupname": "English language",
//   "clues": [
//     {
//       "message": "possible prefix error",
//       "candidate": "979-10-90648-52-4",
//       "groupname": "France"
//     }
//   ]
// }

ISBN.audit('978-1-0906-4852-4')
// {
//   "source":"978-1-0906-4852-4",
//   "validIsbn":false,
//   "clues":[
//     {
//       "message":"checksum hints different prefix",
//       "candidate":"979-10-90648-52-4",
//       "groupname":"France"
//     }
//   ]
// }

groups

ISBN.groups['978-99972']
// => {
//   name: 'Faroe Islands',
//   ranges: [ [ '0', '4' ], [ '50', '89' ], [ '900', '999' ] ]
// }

CLI

Installing the module globally (npm install -g isbn3) will make the following commands available from your terminal.

If you installed locally (npm install isbn3), the command can be accessed from the project directory at ./node_modules/.bin, or just by their filename in npm scripts.

isbn

isbn <isbn> <format>

Valid ISBN input examples:
- 9781491574317
- 978-1-4915-7431-7
- 978-1491574317
- isbn:9781491574317
- 9781-hello-491574317
- 030433376X
- 0-304-33376-X

Formats:
- h: hyphen
- n: no hyphen
- 13: ISBN-13 without hyphen
- 13h: ISBN-13 with hyphen (default)
- 10: ISBN-10 without hyphen
- 10h: ISBN-10 with hyphen
- prefix, group, publisher, article, check, check10, check13: output ISBN part value
- data: output all this data as JSON

isbn-audit

Return the results of the audit function as JSON

isbn-audit <isbn>

This command also accepts a stream of newline-delimited isbns and outputs a stream of newline-delimited JSON, where each line corresponds to an ISBN that is either invalid or that could be suspect of being malformed. Valid ISBN with no possible malformation detected don't return anything. echo ' 9784873113364 9781090648525 978-1-0906-4852-4 ' | isbn-audit > audit_data.ndjson

isbn-checksum

Return the checksum that would correspond to the passed input (ignoring its current checksum if any).

isbn-checksum <isbn>

isbn-checksum 978-4-87311-336-4
# {
#   "input": "978-4-87311-336-4",
#   "checksumCalculatedFrom": "978487311336",
#   "checksum": "4",
#   "isbn": "978-4-87311-336-4"
# }

isbn-checksum 978-4-87311-336-1
# {
#   "input": "978-4-87311-336-1",
#   "checksumCalculatedFrom": "978487311336",
#   "checksum": "4",
#   "isbn": "978-4-87311-336-4"
# }

isbn-checksum 978-4-87311-336
# {
#   "input": "978-4-87311-336",
#   "checksumCalculatedFrom": "978487311336",
#   "checksum": "4",
#   "isbn": "978-4-87311-336-4"
# }

isbn-checksum 978487311336
# {
#   "input": "978487311336",
#   "checksumCalculatedFrom": "978487311336",
#   "checksum": "4",
#   "isbn": "978-4-87311-336-4"
# }


isbn-checksum 978-4-87311-336-1

Benchmark

Indicative benchmark, nothing super scientific, YMMV.

Running npm run benchmark a few times on some Linux machine with Node.Js v8.12 produced in average the following mesure:

  • isbn3
  • load module: 6ms
  • parse 4960 non-hyphenated ISBNs in around 110ms
  • load module: 4.5ms
  • parse 4960 non-hyphenated ISBNs in around 285ms

The difference is mainly due to the generation of a map of groups in isbn3, which takes more time a initialization but makes groups lookups much faster.

Development

Test Suite

To run the lint/test suite use:

npm test

Update Groups data

Groups data are fetched from isbn-international.org, and are critical to how this lib parses ISBNs. Unfortunately, those groups aren't fixed once for all, and we need to update those data periodically.

Once a month, a CI job takes care of updating ISBN groups data and publishing a patch version: Auto-update groups data

To get the latest data, you thus just need to update to the latest version (beware of breaking changes if that makes you switch to a new major version though):

npm install isbn3@latest

See also