{"id":16765212,"url":"https://github.com/devlato/machine-readable-zone","last_synced_at":"2025-04-10T18:43:38.081Z","repository":{"id":68309255,"uuid":"120933175","full_name":"devlato/machine-readable-zone","owner":"devlato","description":"Machine-readable passport code generator","archived":false,"fork":false,"pushed_at":"2023-02-28T09:16:35.000Z","size":408,"stargazers_count":6,"open_issues_count":4,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-24T16:27:50.393Z","etag":null,"topics":["cli","command-line","command-line-tool","generate","generator","javascript","library","machine","machine-readable-zone","mrz","node","node-js","node-module","nodejs","reading","ts","typescript","typescript-library","typings"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devlato.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-02-09T17:07:46.000Z","updated_at":"2024-01-04T11:03:22.000Z","dependencies_parsed_at":"2024-02-01T06:15:08.748Z","dependency_job_id":null,"html_url":"https://github.com/devlato/machine-readable-zone","commit_stats":{"total_commits":21,"total_committers":1,"mean_commits":21.0,"dds":0.0,"last_synced_commit":"385e024fc18e994f678194123b360433ba09b283"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devlato%2Fmachine-readable-zone","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devlato%2Fmachine-readable-zone/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devlato%2Fmachine-readable-zone/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devlato%2Fmachine-readable-zone/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devlato","download_url":"https://codeload.github.com/devlato/machine-readable-zone/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247847609,"owners_count":21006099,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line","command-line-tool","generate","generator","javascript","library","machine","machine-readable-zone","mrz","node","node-js","node-module","nodejs","reading","ts","typescript","typescript-library","typings"],"created_at":"2024-10-13T05:28:45.897Z","updated_at":"2025-04-10T18:43:38.061Z","avatar_url":"https://github.com/devlato.png","language":"TypeScript","readme":"# Machine-readable zone code generator\n\nThis library helps to generate [Machine-readable zone codes](https://en.wikipedia.org/wiki/Machine-readable_passport). \nIt's implemented with Node.js and TypeScript. It provides both CLI tool and programmatic API.\n\n[![Build Status](https://travis-ci.org/devlato/machine-readable-zone.svg?branch=master)](https://travis-ci.org/devlato/machine-readable-zone)\n[![Coverage Status](https://coveralls.io/repos/github/devlato/machine-readable-zone/badge.svg?branch=master)](https://coveralls.io/github/devlato/machine-readable-zone?branch=master)\n[![Code Climate](https://codeclimate.com/github/devlato/machine-readable-zone/badges/gpa.svg)](https://codeclimate.com/github/devlato/machine-readable-zone)\n[![Issue Count](https://codeclimate.com/github/devlato/machine-readable-zone/badges/issue_count.svg)](https://codeclimate.com/github/devlato/machine-readable-zone)\n[![npm version](https://badge.fury.io/js/machine-readable-zone.svg)](https://badge.fury.io/js/machine-readable-zone)\n\n\n## Dependencies:\n\nThe project depends on the following technologies and libraries:\n* `Node.js`;\n* `TypeScript`;\n* `jest` and `ts-jest`;\n* `ts-node-dev`;\n* `tslint` and `tslint-config-airbnb`.\n\nAs you see, there no dependencies but various dev tools.\n\n\n## Installation\n\n(These installation instructions would be valid after publishing, so the package name could change).\n\nLet's consider you use [Yarn](https://yarnpkg.com/) as your package manager. If you use [npm](https://www.npmjs.com/), \nit would pretty easy for you to translate the commands using \nthis [cheatsheet](https://github.com/areai51/yarn-cheatsheet).\n\nTo install it as a global binary, use the following command:\n\n```sh\n$ yarn global add machine-readable-zone\n```\n\nTo install it as your project dependency, run:\n\n```sh\n$ yarn add machine-readable-zone\n```\n\n\n## Usage\n\nIf you have the package installed globally, you can use `machine-readable-zone` as binary name. Otherwise keep \nin mind that you can use `./node_modules/machine-readable-zone/dist/index.js` or `yarn start` (in development mode) \ninstead of `machine-readable-zone`.\n\n```sh\n$ machine-readable-zone --help\n\n  Syntax: machine-readable-zone [options]\n  Options:\n  --first-name:          [*] First name\n  --last-name:           [*] Last name\n  --passport-number:     [*] Passport number (9 digits)\n  --country-code:        [*] Country code (ISO 3166-1 alpha-3*)\n  --nationality:         [*] Nationality (ISO 3166-1 alpha-3*)\n  --gender:              [*] Sex/gender (M/F)\n  --valid-until-date:    [*] Date of validity (dd.mm.yyyy)\n  --personal-number:         Personal number (14 digits)\n  \n  --countries            Print all the supported countries with codes\n  --version              Print package version\n  --help                 Print this help message\n```\n\nSoftware needs your personal data to generate the code, so please provide it according to the expected formats.\n\n\n## API\n\nThe library exports some methods:\n* `generateMRZ` – the function that actually generates the code. It needs a valid data;\n* `generateMRZFromCommandLineArgs` – the function that runs in a command line mode. \n  It parses and validates the data and generates the code;\n* `validateData` – validates the given data according to the `schema` (`ValidationSchema` type). \n  If you want to use it, you need to pass a validation schema;\n* `ParamsValidationSchema` – the schema that `generateMRZFromCommandLineArgs` uses internally. \n  It's a default one and you can pass it to `validateData`.\n  \n### Basic programmatic example\n\nYou could use `generateMRZ` function to generate a machine-readable zone code. \nPlease note that this function takes args that have to be already validated.\n\n```typescript\nimport { generateMRZ } from 'machine-readable-zone';\n\nconst code = generateMRZ({\n  user: {\n    firstName: 'Ivan',\n    lastName: 'Petrov',\n    passportNumber: '123456789',\n    countryCode: 'RUS',\n    nationality: 'RUS',\n    birthday: '01.02.1983',\n    gender: 'M',\n    validUntilDay: '02.03.2028',\n    personalNumber: '12345678901234',\n  },\n});\n\n// Prints P\u003cRUSPETROV\u003c\u003cIVAN\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\\n1234567897RUS8302010M28030211234567890123454\nconsole.log(code);\n```\n\n### Using validation shipped with library\n\nA basic validation function is included in library as well. If you're feeling lazy ot just satisfied with\nlibrary validation results, feel free to use it.\n\n```typescript\nimport { validateData } from 'machine-readable-zone';\n\nconst validationResult = validateData({\n  user: {\n    firstName: '',\n    lastName: '',\n    passportNumber: '123456789',\n    countryCode: 'RUS',\n    nationality: 'RU',\n    birthday: '01/02/1983',\n    gender: 'M',\n    validUntilDay: '02.03.2028',\n    personalNumber: '12345678901234',\n  },\n});\n\n/* \n * Prints: \n * { \n *   isValid: false,\n *   errors: [\n *     { fieldName: 'firstName', error: 'value should non be empty' },\n *     { fieldName: 'lastName', error: 'value should non be empty' },\n *     { fieldName: 'nationality', error: 'country RU not found. Did you mean RUS?' },\n *     { fieldName: 'birthday', error: 'value 01/02/1983 should be an existing date in dd.mm.yyyy format' },\n *   ],\n * }\n */\nconsole.log(validationResult);\n```\n\n### Public interface\n\nThe library exposes the following typings:\n\n```typescript\ndeclare module 'machine-readable-zone' {\n  export interface UserInfo {\n    firstName: string;\n    lastName: string;\n    passportNumber: string;\n    countryCode: string;\n    nationality: string;\n    birthday: string;\n    gender: string;\n    validUntilDay: string;\n    personalNumber: string;\n  }\n\n  export type CommandLineArgs = string[];\n\n  export interface MRZGeneratorArgs {\n    user: UserInfo;\n  }\n\n  export interface MRZCommandLineArgs extends MRZGeneratorArgs {\n    version: boolean;\n    help: boolean;\n    countries: boolean;\n  }\n\n  export type MRZGenerationResult = string;\n\n  type CommandLineArgsMRZGenerator = (args: CommandLineArgs) =\u003e void;\n  type MRZGenerator = (args: MRZGeneratorArgs) =\u003e MRZGenerationResult;\n\n  interface FieldError {\n    fieldName: string;\n    error: string;\n  }\n\n  interface ArgsValidationResult {\n    isValid: boolean;\n    errors: FieldError[];\n  }\n\n  type SchemaValidator = (args: MRZGeneratorArgs) =\u003e ArgsValidationResult;\n\n  type OptionalString = string | null;\n\n  type FieldValidationResult = OptionalString;\n\n  type Validator = (value: any) =\u003e FieldValidationResult;\n\n  interface ValidationSchema {\n    firstName: Validator;\n    lastName: Validator;\n    passportNumber: Validator;\n    countryCode: Validator;\n    nationality: Validator;\n    birthday: Validator;\n    gender: Validator;\n    validUntilDay: Validator;\n    personalNumber: Validator;\n  }\n\n  export const generateMRZFromCommandLineArgs: CommandLineArgsMRZGenerator;\n  export const generateMRZ: MRZGenerator;\n  export const validateData: SchemaValidator;\n  export const ParamsValidationSchema: ValidationSchema;\n}\n```\n\n\n## Building the project\n\nIt is recommend to manage Node versions with [NVM](https://github.com/creationix/nvm).\n\nAfter cloning the project, run\n\n```sh\n$ yarn\n``` \n\nto install the project dependencies. Project has only development dependencies: TypeScript, tslint, jest, etc.\nAs the command succeeded, type\n\n```sh\n$ yarn build\n```\n\nto build the project locally.\n \n\n## Copyright\n\nAuthor: Denis Tokarev ([@devlato](https://github.com/devlato))\n\nLicense: MIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevlato%2Fmachine-readable-zone","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevlato%2Fmachine-readable-zone","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevlato%2Fmachine-readable-zone/lists"}