{"id":17359137,"url":"https://github.com/nathanjhood/base64","last_synced_at":"2026-05-08T18:32:03.855Z","repository":{"id":214742678,"uuid":"737256571","full_name":"nathanjhood/base64","owner":"nathanjhood","description":"Base64 encode/decode with CLI and NodeJS Addon in C++.","archived":false,"fork":false,"pushed_at":"2024-02-16T20:32:56.000Z","size":286,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-27T16:17:19.329Z","etag":null,"topics":["base64","cli","cmake","cmake-js","command-line","command-line-interface","command-line-tool","cpp","decoder","encoder","encoder-decoder","javascript","node-addon","node-addon-api","node-api","typescript"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nathanjhood.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":"2023-12-30T11:19:00.000Z","updated_at":"2024-01-07T04:49:52.000Z","dependencies_parsed_at":"2023-12-30T12:25:24.430Z","dependency_job_id":"a636f133-9ad4-4ad3-8dad-aebfd94824a9","html_url":"https://github.com/nathanjhood/base64","commit_stats":null,"previous_names":["nathanjhood/base64"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nathanjhood/base64","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nathanjhood%2Fbase64","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nathanjhood%2Fbase64/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nathanjhood%2Fbase64/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nathanjhood%2Fbase64/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nathanjhood","download_url":"https://codeload.github.com/nathanjhood/base64/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nathanjhood%2Fbase64/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32792030,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"ssl_error","status_checked_at":"2026-05-08T08:22:45.650Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["base64","cli","cmake","cmake-js","command-line","command-line-interface","command-line-tool","cpp","decoder","encoder","encoder-decoder","javascript","node-addon","node-addon-api","node-api","typescript"],"created_at":"2024-10-15T19:08:19.788Z","updated_at":"2026-05-08T18:32:03.832Z","avatar_url":"https://github.com/nathanjhood.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# base64\n\nBase64 encode/decode CLI in C++.\n\n```.sh\n$ base64 [OPTIONS] [FILE]...\n```\n\nBase64 encode/decode functions in NodeJs.\n\n```.js\nimport base64 from \"@nathanjhood/base64\";\n\nconsole.log(base64.encode(\"foobar\"));\n```\n\n## Content\n\n- [Usage](https://github.com/nathanjhood/base64/tree/main#usage)\n  - [Command Line Interface](https://github.com/nathanjhood/base64/tree/main#command_line_interface)\n  - [NodeJs Interface](https://github.com/nathanjhood/base64/tree/main#nodejs_interface)\n- [Goals](https://github.com/nathanjhood/base64/tree/main#goals)\n- [Examples](https://github.com/nathanjhood/base64/tree/main#examples)\n- [About](https://github.com/nathanjhood/base64/tree/main#about)\n- [Build from source](https://github.com/nathanjhood/base64/tree/main#build-from-source)\n- [Coming Soon](https://github.com/nathanjhood/base64/tree/main#coming-soon)\n- [Acknowledgments](https://github.com/nathanjhood/base64/tree/main#acknowledgments)\n\n## Usage\n\n### Command Line Interface\n\n*PLEASE NOTE: The following steps assume that you have [built the executable from the source code](https://github.com/nathanjhood/base64/tree/main#build-from-source) and it is located at ```\u003cproject folder\u003e/build/bin/base64```, as per the provided build-script.*\n\nLet's say we have a file on disk that we want to encode to base 64...\n\n```.sh\n# tst.txt\n\nf\nfo\nfoo\nfoob\nfooba\nfoobar\n\n```\n\nWe can simply pass the file's location as an argument to base64 to get a readout:\n\n```.sh\n$ ./build/bin/base64 tst.txt\n\nZg==\nZm8=\nZm9v\nZm9vYg==\nZm9vYmE=\nZm9vYmFy\n```\n\nFor further human readability, we can include the line numbers of the file with the ```-n``` (or ```---show-lines```) flag:\n\n```.sh\n$ ./build/bin/base64 -n tst.txt\n     1\n     2  Zg==\n     3  Zm8=\n     4  Zm9v\n     5  Zm9vYg==\n     6  Zm9vYmE=\n     7  Zm9vYmFy\n     8\n```\n\nAs a result of this flag, we can clearly see that there are two empty lines in the file (lines 1 and 8).\n\nIn the case of more complex input/output files, it can also be helpful to report the line endings as ```$```. To do this, include the ```-E``` (or ```--show-ends```) flag:\n\n```.sh\n$ ./build/bin/base64 -n -E tst.txt\n     1  $\n     2  Zg==$\n     3  Zm8=$\n     4  Zm9v$\n     5  Zm9vYg==$\n     6  Zm9vYmE=$\n     7  Zm9vYmFy$\n     8  $\n```\n\nYou can write the output to a file on disk with the streaming operator (place ```\u003e\u003e name.ext``` after the command):\n\n```.sh\n$ ./build/bin/base64 tst.txt \u003e\u003e foo.txt\n```\n\nTo decode the data back again, just add the ```--decode``` flag:\n\n```.sh\n$ ./build/bin/base64 --decode --show-lines --show-ends foo.txt\n     1  $\n     2  f$\n     3  fo$\n     4  foo$\n     5  foob$\n     6  fooba$\n     7  foobar$\n     8  $\n```\n\nTo go full circle, just ```--decode``` back to a new file:\n\n```.sh\n$ ./build/bin/base64 --decode foo.txt \u003e\u003e bar.txt\n```\n\nYou can also pass the ```--encode``` flag when you want to be specific:\n\n```.sh\n$ ./build/bin/base64 --encode --show-lines bar.txt\n     1\n     2  Zg==\n     3  Zm8=\n     4  Zm9v\n     5  Zm9vYg==\n     6  Zm9vYmE=\n     7  Zm9vYmFy\n```\n\n*PLEASE NOTE: only one mode - encode or decode - can be specified per run, and if neither flag is passed, then the encode function will be selected by default.*\n\n### NodeJs Interface\n\n*PLEASE NOTE: The following assumes that you have both a C++ compiler toolchain, and CMake, installed on your system. These commands will build the binary from the source code, which means the system requirements are the same as when [building from source](https://github.com/nathanjhood/base64/tree/main#build-from-source), but those build steps are not required - see the below, instead.*\n\nBuild and run with npm:\n\n```.sh\n$ npm install \u0026\u0026 npm run start\n```\n\nOr, build and run with yarn:\n\n```.sh\n$ yarn \u0026\u0026 yarn start\n```\n\nThe above commands will build the NodeJs module from source, then execute the contents of ```index.js``` which serves as a demonstration.\n\nCurrently the NodeJS binary module implements both the ```encode()``` and ```decode()``` functions, which are exported from ```lib/base64.node.js```. \u003cb\u003eSince the file input parsing is currently a part of the CLI implementation, the NodeJS module parses input strings, not files\u003c/b\u003e. Just import/require ```base64``` from this file, and call the functions:\n\n```.js\n// index.js\n\nconst base64 = require(\"./lib/base64.node\");\n...\n\nconsole.log(base64.encode(\"\"));\nconsole.log(base64.encode(\"f\"));\nconsole.log(base64.encode(\"fo\"));\nconsole.log(base64.encode(\"foo\"));\nconsole.log(base64.encode(\"foob\"));\nconsole.log(base64.encode(\"fooba\"));\nconsole.log(base64.encode(\"foobar\"));\nconsole.log(base64.encode(\"\"));\n\n...\n```\n\nRun ```node ./test/index.js``` to execute the test script:\n\n```\n...\n\nZg==\nZm8=\nZm9v\nZm9vYg==\nZm9vYmE=\nZm9vYmFy\n\n...\n```\n\n*PLEASE NOTE: the 'url' version of the base64 alphabet is much more well-suited for usage in tasks where javascript is often deployed.*\n\nBoth functions also have an additional second parameter, 'urlMode' , which accepts a boolean value. Setting this parameter to 'true' will switch to the base64 alphabet; this alphabet supports URL-like strings:\n\n```.sh\n// encoder mode test - using non-url alphabet\nconsole.log(base64.encode(\"=\", false));\nconsole.log(base64.encode(\"/\", false));\nconsole.log(base64.encode(\"-\", false));\nconsole.log(base64.encode(\"_\", false));\n\n// encoder mode test - using url alphabet\nconsole.log(base64.encode(\"=\", true));\nconsole.log(base64.encode(\"/\", true));\nconsole.log(base64.encode(\"-\", true));\nconsole.log(base64.encode(\"_\", true));\n```\n\nYou can also access the built CLI executable (and all of it's options) directly from the npm script:\n\n```.sh\n$ npm run base64 --encode --show-lines tst.txt\n\n// or...\n\n$ yarn base64 --encode --show-lines tst.txt\n```\n\nYou may also simply add this project to your NodeJs package dependencies and import/require it to use the module:\n\n```.sh\n$ npm install https://github.com/nathanjhood/base64 --save\n\n// or\n\n$ yarn add https://github.com/nathanjhood/base64\n```\n\n```.js\nimport base64 from \"@nathanjhood/base64\";\n\nconsole.log(base64.encode(\"foobar\"));\n...\n```\n\n## Goals\n\nMy primary interest in this project is to extend functionality to include other algorithms and alphabets, such as Base32, Hex, etc, with a unified interface - or perhaps just a single interface, eventually - and implement a variety of hand-rolled alphabets as a Node C++ addon, beyond the standard ```atob()```.\n\nThis project will serve as a workbench for certain aspects of the intended final application, mostly focusing on the underlying algorithm, as well as interfacing with it from other code - the provided CLI being one example of a possible consumer runtime, and NodeJs being another.\n\n## Examples\n\nWill parse almost any file type the OS can handle:\n\n```.sh\n$ ./build/bin/base64 icon__32x32.png\n\niVBORw0=\nGg==\nAAAADUlIRFIAAAAgAAAAIAgGAAAAc3p69AAAAAlwSFlzAAALEwAACxMBAJqcGAAAAAFzUkdCAK7OHOkAAAAEZ0FNQQAAsY8L/GEFAAAD3klEQVR4Ae1XS08TURS+M9NSngIhwUB4hWLiookLSQgLYxqkPHZsXPkTXKnRjcGwdaMrEo1BDbpwoZK6QKQJEHFjAk1MA6Qttg3UpLSF0gZKXzN+p6Gm7XQ6fbjTL7k50zn3nvvd87pTxv51cEo...\n```\n\nCan be useful for writing contents to new files by streaming:\n\n```.sh\n$ ./build/bin/base64 icon__32x32.png \u003e\u003e icon__32x32.png.base64.txt\n```\n\nAccepts multiple files as arguments in a single command:\n\n```.sh\n$ ./build/bin/base64 package.json include/base64/base64.h\n\n\n# file: package.json\n\new==\nICAibmFtZSI6ICJiYXNlNjQiLA==\nICAidmVyc2lvbiI6ICIwLjAuMCIs\nICAibWFpbiI6ICJpbmRleC5qcyIs\nICAiYXV0aG9yIjogIlN0b25leURTUCA8bmF0aGFuamhvb2RAZ29vZ2xlbWFpbC5jb20+Iiw=\nICAibGljZW5zZSI6ICJNSVQiLA==\nICAic2NyaXB0cyI6IHs=\nICAgICJwb3N0aW5zdGFsbCI6ICJjbWFrZS1qcyBjb21waWxlIiw=\nICAgICJjb25maWd1cmUiOiAiY21ha2UtanMgY29uZmlndXJlIiw=\nICAgICJyZWNvbmZpZ3VyZSI6ICJjbWFrZS1qcyByZWNvbmZpZ3VyZSIs\nICAgICJidWlsZCI6ICJjbWFrZS1qcyBidWlsZCIs\nICAgICJyZWJ1aWxkIjogImNtYWtlLWpzIHJlYnVpbGQiLA==\nICAgICJjbGVhbiI6ICJjbWFrZS1qcyBjbGVhbiIs\nICAgICJ3aXBlIjogImNtYWtlLWpzIGNsZWFuICYmIHJtIC1ydmYgLi9ub2RlX21vZHVsZXMiLA==\nICAgICJzdGFydCI6ICIuL2J1aWxkL2Jpbi9iYXNlNjQgZmF2aWNvbi5pY28gaWNvbl9fMzJ4MzIucG5nIg==\nICB9LA==\nICAiZGVwZW5kZW5jaWVzIjogew==\nICAgICJjbWFrZS1qcyI6ICJeNy4yLjEi\nICB9\nfQ==\n\n\n# file: include/base64/base64.h\n\nLyoq\nICogQGZpbGUgYmFzZTY0Lmg=\nICogQGF1dGhvciBSZW7DqSBOeWZmZW5lZ2dlciAocmVuZS5ueWZmZW5lZ2dlckBhZHAtZ21iaC5jaCk=\nICogQGJyaWVm\nICogQHZlcnNpb24gMC4x\nICogQGRhdGUgMjAyMy0xMi0yOQ==\nICo...\n```\n\nUse the output data directly in various software design tasks:\n\n```.sh\n# styles.css\nhtml {\n    background-image: url(\"data:image/png;base64,ICogQGF1dGhvciBSZW7DqSBOeWZmZW5lZ....\");\n}\n```\n\n```.sh\n# index.html\n\u003chead\u003e\n    \u003clink rel=\"favicon\" type=\"image/x-icon\" href=\"Content-Type: image/x-icon;ICogQGF1dGhvciBSZW7DqSBOeWZmZW5lZ....\"\u003e\n\u003c/head\u003e\n```\n\n## About\n\nThe encoding process represents 24-bit groups of input bits as output\nstrings of 4 encoded characters.  Proceeding from left to right, a\n24-bit input group is formed by concatenating 3 8-bit input groups.\nThese 24 bits are then treated as 4 concatenated 6-bit groups, each\nof which is translated into a single character in the base 64\nalphabet.\n\n```\n  \u003c===========\u003e                                   1st character\n                  \u003c===========\u003e                   2nd character\n                                  \u003c===========\u003e   3rd character\n+---------------+---------------+---------------+\n| \u003c     1     \u003e | \u003c     2     \u003e | \u003c     3     \u003e | 3 groups (8 bit)\n+---------------+---------------+---------------+\n|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0| Stream (24 bits)\n+-----------+---+-------+-------+---+-----------+\n|\u003c    1    \u003e|\u003c    2    \u003e|\u003c    3    \u003e|\u003c    4    \u003e| 4 groups (6 bit)\n+-----------+-----------+-----------+-----------+\n|5 4 3 2 1 0|5 4 3 2 1 0|5 4 3 2 1 0|5 4 3 2 1 0| Index  (24 bits)\n\n                                     \u003c=========\u003e  4th character\n                         \u003c=========\u003e              3rd character\n             \u003c=========\u003e                          2nd character\n \u003c=========\u003e                                      1st character\n```\n\nEach 6-bit group is used as an index into an array of 64 printable\ncharacters.  The character referenced by the index is placed in the\noutput string.\n\nA 65-character subset of US-ASCII is used, enabling 6 bits to be\nrepresented per printable character.  (The extra 65th character, \"=\",\nis used to signify a special processing function.)\n\nEach 6-bit group is used as an index into an array of 64 printable\ncharacters.  The character referenced by the index is placed in the\noutput string.\n\n```\n                  The Base 64 Alphabet\n\n  Value Encoding  Value Encoding  Value Encoding  Value Encoding\n       0 A           17 R            34 i            51 z\n       1 B           18 S            35 j            52 0\n       2 C           19 T            36 k            53 1\n       3 D           20 U            37 l            54 2\n       4 E           21 V            38 m            55 3\n       5 F           22 W            39 n            56 4\n       6 G           23 X            40 o            57 5\n       7 H           24 Y            41 p            58 6\n       8 I           25 Z            42 q            59 7\n       9 J           26 a            43 r            60 8\n      10 K           27 b            44 s            61 9\n      11 L           28 c            45 t            62 +\n      12 M           29 d            46 u            63 /\n      13 N           30 e            47 v\n      14 O           31 f            48 w         (pad) =\n      15 P           32 g            49 x\n      16 Q           33 h            50 y\n```\n\n```.txt\n\nBASE64 ENCODE:\n\n  \u003c===========\u003e                                   1st character\n                  \u003c===========\u003e                   2nd character\n                                  \u003c===========\u003e   3rd character\n+---------------+---------------+---------------+\n| \u003c     1     \u003e | \u003c     2     \u003e | \u003c     3     \u003e | 3 groups (8 bit)\n+---------------+---------------+---------------+\n|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0| Stream (24 bits)\n+-----------+---+-------+-------+---+-----------+\n|\u003c    1    \u003e|\u003c    2    \u003e|\u003c    3    \u003e|\u003c    4    \u003e| 4 groups (6 bit)\n+-----------+-----------+-----------+-----------+\n|5 4 3 2 1 0|5 4 3 2 1 0|5 4 3 2 1 0|5 4 3 2 1 0| Index (24 bits)\n\n                                     \u003c=========\u003e  4th character\n                         \u003c=========\u003e              3rd character\n             \u003c=========\u003e                          2nd character\n \u003c=========\u003e                                      1st character\n\n\nBASE64 DECODE:\n\n \u003c=========\u003e                                      1st character\n             \u003c=========\u003e                          2nd character\n                         \u003c=========\u003e              3rd character\n                                     \u003c=========\u003e  4th character\n+-----------+-----------+-----------+-----------+\n|\u003c    1    \u003e|\u003c    2    \u003e|\u003c    3    \u003e|\u003c    4    \u003e| 4 groups (6 bit)\n+-----------+-----------+-----------+-----------+\n|5 4 3 2 1 0|5 4 3 2 1 0|5 4 3 2 1 0|5 4 3 2 1 0| Index (24 bits)\n+-----------+---+-------+-------+---+-----------+\n| \u003c     1     \u003e | \u003c     2     \u003e | \u003c     3     \u003e | 3 groups (8 bit)\n+---------------+---------------+---------------+\n|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0| Stream (24 bits)\n\n                                  \u003c===========\u003e   3rd character\n                  \u003c===========\u003e                   2nd character\n  \u003c===========\u003e                                   1st character\n\n```\n\n## Build from source\n\nSystem Requirements:\n- C++ compiler (GNU, MSVC...)\n- CMake\n- Ninja (optional/recommended)\n\nCheck out out the project:\n\n```.sh\n$ git clone https://github.com/nathanjhood/base64.git\n$ cd base64\n```\n\nConfigure the library and executable with CMake:\n\n```.sh\n$ cmake -S . -B ./build\n```\n*NOTE: The '-S .' arg tells CMake to start from the current directory. The -B arg tells CMake to place it's output in the 'build' directory (which you can of course change if you wish).*\n\nBuild it (replace with ```make``` or whichever generator you prefer):\n```\n$ ninja ./build\n```\n\nTry running the built executable:\n\n```.sh\n$ ./build/bin/base64 icon__32x32.png\n\n# output should appear...\n...\n```\n\n## Coming soon...\n\nCurrently working on enhancing the CLI switch argument for the different modes (encode, decode, possibly a 'diff' mode for testing, debugging, etc). Furthermore, colorization and styling of line numbers and line ending chars is already in the codebase, but will need a bit of system-detection logic to ensure that the end-user's terminal actually [supports colourized output](https://linux.die.net/man/5/terminfo). Finally, the CLI should also accept strings passed in as arguments, in place of any input file, if a certain flag is used.\n\nThe CLI is compiled into a static library that the executable is then linked to; this should probably be amended such that the CLI *only* gets baked into the executable and is *not* compiled into a seperate library, because the CLI is really part of the executable, *not* part of the base64 implementation; it is not really intended to be shared with other code, besides ```main()```.\n\nWindows support depends on defining a 'wmain()' entry in place of the usual 'main()', and parsing support for ```w_char``` type. Flags are sometimes prepended with a ```/``` instead of a ```-``` - depending on how much Windows integration is required. Many command line executables running on Windows terminals do accept the usual UNIX-style argument syntax, these days.\n\n*PLEASE NOTE: This project should not really be installed system-wide nor placed in your operating system's ```PATH```, due to the naming conflict with the actual system-level base64 implementation.*\n\n*Due to this, and also some interest in implementing further encode/decode algorithms as well as implementing the entire package as NodeJs binary addons, this project will likely either be renamed, or deprecated in favor of a larger, more realized project.*\n\n## Thanks for reading!\n\n[Nathan J. Hood](https://github.com/nathanjhood)\n\n## Acknowledgements:\n\n- [\"The Base16, Base32, and Base64 Data Encodings\"](https://datatracker.ietf.org/doc/html/rfc4648); S. Josefsson (Copyright (C) 2006 The Internet Society).\n\n- 'base64.cpp'; The central encode/decode algorithm is a slightly modified implementation taken from René Nyffenegger's 'base64.cpp' (Copyright (C) 2004-2008 René Nyffenegger) from the below discussion:\n\n- [https://stackoverflow.com/questions/180947/base64-decode-snippet-in-c](https://stackoverflow.com/questions/180947/base64-decode-snippet-in-c)\n\n- [A more recent (version 2) revision of this algorithm is also publically available](https://renenyffenegger.ch/notes/development/Base64/Encoding-and-decoding-base-64-with-cpp/). My reasons for adapting an earlier version is because I intend to attempt several other encode/decode algorithms using a similar approach to this implementation, which has slightly less of the functionality tailored specifically for base64, and thus shall be more adaptable into other forms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnathanjhood%2Fbase64","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnathanjhood%2Fbase64","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnathanjhood%2Fbase64/lists"}