Wisdom Garden QR Code Format Library

‼️ Rules ‼️

1. The value must be a number, string, or boolean
2. Nested data is not supported
3. For the array in the config.ts file, data can only be appended.

Install

npm install @wisdomgarden/qrcode-format

Usage

import { decodeData, encodeData } from "@wisdomgarden/qrcode-format";

const testJson = {
    "courseId": 1,
    "foo": "bar"
}

const encodedData = encodeData(testJson);
console.log(encodedData);

const decodedData = decodeData(encodedData);
console.log(decodedData);

Sample

{"courseId":1,"foo":"bar"}

encodeURIComponent -->

%7B%22courseId%22%3A1%2C%22foo%22%3A%22bar%22%7D

encodedData -->

0~%101!foo~bar

Add new key or value

Append data to the array in src/config.ts only, without modifying existing data.

How it Works

In this library, a JSON data item must have key-value pairs, where the key must be a string, and the value must be a boolean, string, or number.

We encode the JSON data into a string using the format: key~value!

The reason for choosing ~ and ! is that they remain unchanged after encodeURIComponent, resulting in the minimal string length.

During decoding, we restore the JSON object by following the same rules in reverse.

However, since the value loses its original data type after being converted to a string, we need to perform special processing.

The items in arrays KEY_ARR and VALUE_ARR will be generated into two separate maps KEY_MAP and VALUE_MAP, using the item as the key, and its base-36 representation as the value.

For keys, we replace them with items from the KEY_MAP array if they exist, as keys are defined as regular strings by us.

For values, we replace them with items from the VALUE_MAP array if they exist, with some special processing:

• If the value is a boolean, we use the ASCII code 26 SUB (substitute) as its prefix, represented by 🎈 in this document:

  🎈0 = false
  🎈1 = true

  This ensures that booleans have a unique identifier and can be correctly restored from a string.

• If the value is an integer, we use the ASCII code 16 DLE (data link escape) as its prefix, represented by 🌳 in this document:

  🌳999 -> 999
  999 -> "999"

  However, this introduces an issue where numbers gain a %10 prefix after encodeURIComponent, increasing the string length by 3 characters.

• To mitigate this, we convert integers to base-36 representation, which can reduce the string length further:

  999 -> 🌳rr -> 999

• For floats, since base-36 cannot represent fractional parts, we split the float at the decimal point and format the integer and fractional parts separately:

  999.999 -> 🌳rr.rr -> 999.999

• If the value is a string and included in VALUE_MAP, it will have a 🎈 prefix to differentiate it from other regular strings:

  🎈2 -> "classroom-exam"
  2 -> "2"

• If the value contains custom user input (e.g., name) that may conflict with ~ and !, we replace these characters with non-printable ASCII codes: ASCII 30 RS (record separator) represented by 🌙 for ~, and ASCII 31 US (unit separator) represented by 🌈 for !:

  "key": "abc~123!" -> key~abc🌙123🌈

These are all the encoding rules; decoding is performed by reversing these operations.