isbn3

isbn3

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

Summary

• Install
• Functions
  • parse
  • asIsbn13
  • asIsbn10
  • hyphenate
  • audit
  • groups
• CLI
  • isbn
  • isbn-audit
  • isbn-checksum
• Benchmark
• Development
  • Test Suite
  • Update Groups
• See also

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": {
//         "isbn13h": "979-10-90648-52-4",
//         "isbn13": "9791090648524",
//         "groupname": "France"
//       }
//     }
//   ]
// }

ISBN.audit('978-1-0906-4852-4')
// {
//   "source": "978-1-0906-4852-4",
//   "validIsbn": false,
//   "clues": [
//     {
//       "message": "Found a matching group and publisher range, but the checksum didn't match. Could the checksum be wrong?",
//       "candidate": {
//         "isbn13h": "978-1-0906-4852-5",
//         "isbn13": "9781090648525",
//         "isbn10h": "1-0906-4852-9",
//         "isbn10": "1090648529",
//         "groupname": "English language"
//       }
//     },
//     {
//       "message": "Checksum hints different prefix",
//       "candidate": {
//         "isbn13h": "979-10-90648-52-4",
//         "isbn13": "9791090648524",
//         "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

• isbn2 (for comparison)

• 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:

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

• isbn-groups: infer a language from an ISBN group