ordered-binary 1.1.3 → 1.2.3

package/README.md

@@ -1,8 +1,34 @@
+[![npm version](https://img.shields.io/npm/dw/ordered-binary)](https://www.npmjs.org/package/ordered-binary)
+[![npm version](https://img.shields.io/npm/v/ordered-binary.svg?style=flat-square)](https://www.npmjs.org/package/ordered-binary)
+[![license](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE)
 <a href="https://dev.doctorevidence.com/"><img src="./assets/powers-dre.png" width="203" /></a>
 
-The ordered-binary provides a representation of JavaScript primitives as NodeJS Buffers, such that there binary values are naturally ordered such that it matches primitive ordering. For example, since -2.0321 > -2.04, then `toBufferKey(-2.0321)` will be greater than `toBufferKey(-2.04)` as a binary representation, in left-to-right evaluation. This is particular useful for storing keys as binaries with something like LevelDB, to avoid any custom sorting.
+The ordered-binary package provides a representation of JavaScript primitives, serialized into binary format (NodeJS Buffers or Uint8Arrays), such that the binary values are naturally ordered such that it matches the natural ordering or values. For example, since -2.0321 > -2.04, then `toBufferKey(-2.0321)` will be greater than `toBufferKey(-2.04)` as a binary representation, in left-to-right evaluation. This is particular useful for storing keys as binaries with something like LMDB or LevelDB, to avoid any custom sorting.
 
-The main module exports two functions:
+The ordered-binary package supports strings, numbers, booleans, symbols, null, as well as an array of primitives. Here is an example of ordering of primitive values:
+```
+Buffer.from([0]) // buffers are left unchanged, and this is the minimum value
+Symbol.for('even symbols')
+-10 // negative supported
+-1.1 // decimals supported
+400
+3E10
+'Hello'
+['Hello', 'World']
+'World'
+'hello'
+['hello', 1, 'world']
+['hello', 'world']
+Buffer.from([0xff])
+```
+
+
+The main module exports these functions:
+
+`writeKey(key: string | number | boolean | null | Array, target: Buffer, position: integer, inSequence?: boolean)` - Writes the provide key to the target buffer
+
+`readKey(buffer, start, end, inSequence)` - Reads the key from the buffer, given the provided start and end, as a primitive value
 
 `toBufferKey(jsPrimitive)` - This accepts a string, number, or boolean as the argument, and returns a `Buffer`.
+
 `fromBufferKey(bufferKey, multiple)` - This accepts a Buffer and returns a JavaScript primitive value. This can also parse buffers that hold multiple values delimited by a byte `30`, by setting the second argument to true (in which case it will return an array).

package/dist/index.cjs

@@ -20,7 +20,14 @@ control character types:
 
 const float64Array = new Float64Array(2);
 const int32Array = new Int32Array(float64Array.buffer, 0, 4);
+new Uint8Array(float64Array.buffer, 2, 6);
+new Uint8Array(float64Array.buffer, 0, 8);
 let nullTerminate = false;
+let textEncoder;
+try {
+	textEncoder = new TextEncoder();
+} catch (error) {}
+
 /*
 * Convert arbitrary scalar values to buffer bytes with type preservation and type-appropriate ordering
 */
@@ -32,9 +39,9 @@ function writeKey(key, target, position, inSequence) {
 	case 'string':
 		let strLength = key.length;
 		let c1 = key.charCodeAt(0);
-		if (c1 < 28) // escape character
+		if (!(c1 >= 28)) // escape character
 			target[position++] = 27;
-		if (strLength < 0x20) {
+		if (strLength < 0x40) {
 			let i, c2;
 			for (i = 0; i < strLength; i++) {
 				c1 = key.charCodeAt(i);
@@ -60,7 +67,12 @@ function writeKey(key, target, position, inSequence) {
 				}
 			}
 		} else {
-			position += target.utf8Write(key, position, 2000);
+			if (target.utf8Write)
+				position += target.utf8Write(key, position);
+			else
+				position += textEncoder.encodeInto(key, target.subarray(position)).written;
+			if (position > target.length - 4)
+				throw new RangeError('String does not fit in target buffer')
 		}
 		break
 	case 'number':
@@ -200,9 +212,12 @@ function readKey(buffer, start, end, inSequence) {
 	}
 	return value
 }
+const enableNullTermination = () => nullTerminate = true;
+
 const encoder = {
 	writeKey,
 	readKey,
+	enableNullTermination,
 };
 const toBufferKey = (key) => {
 	let buffer = Buffer.alloc(2048);
@@ -267,12 +282,10 @@ function finishUtf8(byte1, src) {
 	}
 }
 
-const enableNullTermination = () => nullTerminate = true;
-
 const readString = eval(makeStringBuilder());
 
 function compareKeys(a, b) {
-	// compare with type consistency that matches ordered-binary
+	// compare with type consistency that matches binary comparison
 	if (typeof a == 'object') {
 		if (!a) {
 			return b == null ? 0 : -1
@@ -319,8 +332,12 @@ const typeOrder = {
 	boolean: 2,
 	number: 3,
 	string: 4
-};
+};
+const MINIMUM_KEY = null;
+const MAXIMUM_KEY = new Uint8Array([0xff]);
 
+exports.MAXIMUM_KEY = MAXIMUM_KEY;
+exports.MINIMUM_KEY = MINIMUM_KEY;
 exports.compareKeys = compareKeys;
 exports.enableNullTermination = enableNullTermination;
 exports.encoder = encoder;

package/index.js

@@ -19,6 +19,11 @@ const int32Array = new Int32Array(float64Array.buffer, 0, 4)
 const uint8Array6 = new Uint8Array(float64Array.buffer, 2, 6)
 const uint8Array8 = new Uint8Array(float64Array.buffer, 0, 8)
 let nullTerminate = false
+let textEncoder
+try {
+	textEncoder = new TextEncoder()
+} catch (error) {}
+
 /*
 * Convert arbitrary scalar values to buffer bytes with type preservation and type-appropriate ordering
 */
@@ -30,9 +35,9 @@ export function writeKey(key, target, position, inSequence) {
 	case 'string':
 		let strLength = key.length
 		let c1 = key.charCodeAt(0)
-		if (c1 < 28) // escape character
+		if (!(c1 >= 28)) // escape character
 			target[position++] = 27
-		if (strLength < 0x20) {
+		if (strLength < 0x40) {
 			let i, c2
 			for (i = 0; i < strLength; i++) {
 				c1 = key.charCodeAt(i)
@@ -58,7 +63,12 @@ export function writeKey(key, target, position, inSequence) {
 				}
 			}
 		} else {
-			position += target.utf8Write(key, position, 2000)
+			if (target.utf8Write)
+				position += target.utf8Write(key, position)
+			else
+				position += textEncoder.encodeInto(key, target.subarray(position)).written
+			if (position > target.length - 4)
+				throw new RangeError('String does not fit in target buffer')
 		}
 		break
 	case 'number':
@@ -198,9 +208,12 @@ export function readKey(buffer, start, end, inSequence) {
 	}
 	return value
 }
+export const enableNullTermination = () => nullTerminate = true
+
 export const encoder = {
 	writeKey,
 	readKey,
+	enableNullTermination,
 }
 export const toBufferKey = (key) => {
 	let buffer = Buffer.alloc(2048)
@@ -265,12 +278,10 @@ function finishUtf8(byte1, src) {
 	}
 }
 
-export const enableNullTermination = () => nullTerminate = true
-
 const readString = eval(makeStringBuilder())
 
 export function compareKeys(a, b) {
-	// compare with type consistency that matches ordered-binary
+	// compare with type consistency that matches binary comparison
 	if (typeof a == 'object') {
 		if (!a) {
 			return b == null ? 0 : -1
@@ -318,3 +329,5 @@ const typeOrder = {
 	number: 3,
 	string: 4
 }
+export const MINIMUM_KEY = null
+export const MAXIMUM_KEY = new Uint8Array([0xff])

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ordered-binary",
   "author": "Kris Zyp",
-  "version": "1.1.3",
+  "version": "1.2.3",
   "description": "Conversion of JavaScript primitives to and from Buffer with binary order matching natural primitive order",
   "license": "MIT",
   "repository": {
@@ -14,6 +14,7 @@
     "test": "mocha tests -u tdd"
   },
   "type": "module",
+  "main": "dist/index.cjs",
   "module": "index.js",
   "exports": {
     ".": {
@@ -30,7 +31,7 @@
   "devDependencies": {
     "@types/node": "latest",
     "chai": "^4",
-    "mocha": "^8.1.3",
-    "rollup": "^1.20.3"
+    "mocha": "^9.1.3",
+    "rollup": "^2.61.1"
   }
 }

package/tests/test.js

@@ -43,6 +43,7 @@ suite('key buffers', () => {
   test('string equivalence', () => {
     assert.strictEqual(fromBufferKey(toBufferKey('4')), '4')
     assert.strictEqual(fromBufferKey(toBufferKey('hello')), 'hello')
+    assert.strictEqual(fromBufferKey(toBufferKey('')), '')
   })
   test('string comparison', () => {
     assertBufferComparison(toBufferKey('4'), toBufferKey('5'))