{"id":21082328,"url":"https://github.com/olsonpm/couchdb-base64","last_synced_at":"2025-03-14T04:43:16.348Z","repository":{"id":80606271,"uuid":"128231773","full_name":"olsonpm/couchdb-base64","owner":"olsonpm","description":null,"archived":false,"fork":false,"pushed_at":"2018-08-03T21:39:18.000Z","size":15,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"dev","last_synced_at":"2025-01-20T23:46:19.133Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/olsonpm.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","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-04-05T16:13:11.000Z","updated_at":"2018-08-03T21:39:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"bf2f89de-8022-4a1d-b3ef-cddc54128b64","html_url":"https://github.com/olsonpm/couchdb-base64","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olsonpm%2Fcouchdb-base64","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olsonpm%2Fcouchdb-base64/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olsonpm%2Fcouchdb-base64/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olsonpm%2Fcouchdb-base64/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/olsonpm","download_url":"https://codeload.github.com/olsonpm/couchdb-base64/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243526853,"owners_count":20305112,"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":[],"created_at":"2024-11-19T20:13:42.941Z","updated_at":"2025-03-14T04:43:16.337Z","avatar_url":"https://github.com/olsonpm.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Base64 intended for use with couchdb\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [What is this?](#what-is-this)\n- [Why create it](#why-create-it)\n- [Install](#install)\n- [Character set used](#character-set-used)\n- [Simple example](#simple-example)\n- [API](#api)\n- [Test](#test)\n  \u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n  \u003cbr\u003e\n\n### What is this?\n\nAn encoding scheme intended for use with couchdb's document ids. It is a naive\nsolution to the problem noted [in their documentation](http://docs.couchdb.org/en/2.1.1/maintenance/performance.html#document-s-id).\n\n\u003e Consequently you should consider generating ids yourself, allocating them\n\u003e sequentially and using an encoding scheme that consumes fewer bytes. For\n\u003e example, something that takes 16 hex digits to represent can be done in 4 base\n\u003e 62 digits (10 numerals, 26 lower case, 26 upper case).\n\n\u003cbr\u003e\n\n### Why create it\n\ntraditional base64 has a few issues that aren't couchdb friendly\n\n- contains the '/' character (gets url-encoded when used as a document id)\n- character table is not ordered the same as ascii, which conflicts with the\n  [goal of allocating sequential ids](https://eager.io/blog/how-long-does-an-id-need-to-be/#locality).\n\n  _I couldn't find why base64's character table is ordered the way it is - please enlighten me!_\n\n`couchdb-base64` solves the above two points by using [unreserved characters (rfc 3986)](https://tools.ietf.org/html/rfc3986#section-2.3) '.' and '-' as\nalternatives to '+' and '/'. It also orders these characters to match\nascii ordering.\n\u003cbr\u003e\n\n### Install\n\nnpm install couchdb-base64\n\u003cbr\u003e\n\n### Character set used\n\n`-.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz`\n\u003cbr\u003e\n\n### Simple example\n\n```js\nconst couchdbBase64 = require('couchdb-base64')\n\nconst timestamp = 123456\n\nconst encodedTimestamp = couchdbBase64.encodeFromUInt({\n  uint: timestamp,\n  totalBits: 24\n}),\n\nassert(encodedTimestamp === '-S7-')\n//\n// The binary math\n//\n// '-' = 0\n// 'S' = 30 * (64 ** 2) = 122880\n// '7' = 9 * (64 ** 1) = 576\n// '-' = 0\n// 122880 + 576 = 123456\n//\n\nconst decoded = couchdbBase64.decodeToUInt(encodedTimestamp)\n\nassert(decoded === timestamp)\n```\n\n### API\n\n`const couchdbBase64 = require('couchdb-base64')`\n\nThe default export holds an object with four methods\n\n_Note: The arguments to these methods are strongly validated prior to running\noperations on them. Due to the low level nature of this library I wanted to\nensure nobody passed values which didn't match the intended use-case_\n\n#### `encodeFromUInt({ uint: \u003cint\u003e, totalBits: \u003cint\u003e }) -\u003e couchdb base64 string`\n\nEncodes the passed uint, zero padded to `totalBits`\n\nArguments\n\n- **uint** is an unsigned integer less than `Number.MAX_SAFE_INTEGER`\n- **totalBits** is a positive integer divisible by 6 (the number of bits which\n  represent a base64 character). totalBits allows you to pad your encoded\n  value so the document id can remain incremental. Because of this, if the\n  uint passed takes more bits to represent than `totalBits`, an error is thrown\n  as it is likely a bug.\n\n#### `decodeToUInt(couchdbBase64String) -\u003e uint`\n\nDecodes the passed couchdb-base64 string to an unsigned integer\n\nArguments\n\n- **couchdbBase64String** a non-empty, valid couchdb-base64 string. If it\n  resolves to a uint larger than Number.MAX_SAFE_INTEGER then an error is\n  thrown.\n\n#### `encodeFromString(nonEmptyString) -\u003e couchdb base64 string`\n\nEncodes the passed string into its couchdb base64 equivalent\n\n_Note: This library was originally built to transform uints such as timestamps\nand random numbers to shorter base64 strings. I came across a need to transform\narbitrary strings into url friendly ids which is why I created this method, but\nfor the most part the uint \u003c--\u003e base64 conversions should be used._\n\n#### `decodeToString(couchdbBase64String) -\u003e string`\n\nDecodes the passed couchdb base64 string into its original value\n\n#### `isCouchdbBase64String(anyString) -\u003e boolean`\n\nReturns whether the the passed string is non-empty and contains only characters\nin the couchdb-base64 character set. Specifically it tests against this\nregex `/^[0-9A-Za-z-.]+$/`\n\n### Test\n\n`./run test`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Folsonpm%2Fcouchdb-base64","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Folsonpm%2Fcouchdb-base64","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Folsonpm%2Fcouchdb-base64/lists"}