@e280/stz 0.0.0-20 → 0.0.0-22

package/README.md

@@ -81,8 +81,57 @@ standard library of environment-agnostic typescript functions we use basically e
 
 <br/>
 
+## Data utilities
+> codecs for representing data in different ways
+
+### BaseX
+- make a BaseX instance
+  ```ts
+  import {BaseX} from "@e280/stz"
+
+  const hex = new BaseX(BaseX.lexicons.hex)
+  ```
+- convert between strings and binary
+  ```ts
+  hex.toBytes("9960cd633a46acfe8307d8a400e842da0d930a75fb8188e0f5da264e4b6b4e5b")
+    // Uint8Array
+
+  hex.fromBytes(bytes)
+    // string
+  ```
+- you can also convert between strings and integers
+  ```ts
+  hex.fromInteger(Date.now())
+    // "197140ac804"
+
+  hex.toInteger(hex)
+    // 1748387940356
+  ```
+- available lexicons include
+	- base2
+	- hex
+	- base36
+	- base58
+	- base62
+	- base64 (with standard padding)
+	- base64url
+- you can make insanely compact timestamps like this:
+  ```ts
+  import {BaseX} from "@e280/stz"
+
+  const base62 = new BaseX(BaseX.lexicons.base62)
+
+  base62.fromInteger(Date.now() / 1000)
+    // "1uK3au"
+  ```
+  - `1748388028` base10 epoch seconds (10 chars)
+  - `1uK3au` base62 epoch seconds (6 chars)
+  - *nice*
+
+<br/>
+
 ## Bytename
-### friendly string encoding for binary data
+> friendly string encoding for binary data
 
 a bytename looks like `"midsen.picmyn.widrep.baclut dotreg.filtyp.nosnus.siptev"`. that's 16 bytes. each byte maps to a three-letter triplet
 
@@ -105,12 +154,12 @@ import {Bytename} from "@e280/stz"
     0xDE, 0xAD, 0xBE, 0xEF,
   ])
 
-	Bytename.fromBytes(bytes, {
-		groupSize: 2, // default is 4
-		groupSeparator: " ",
-		wordSeparator: ".",
-	})
-	  // "ribmug.hilmun ribmug.hilmun"
+  Bytename.fromBytes(bytes, {
+    groupSize: 2, // default is 4
+    groupSeparator: " ",
+    wordSeparator: ".",
+  })
+    // "ribmug.hilmun ribmug.hilmun"
   ```
 
 <br/>

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@e280/stz",
-	"version": "0.0.0-20",
+	"version": "0.0.0-22",
 	"description": "everyday ts fns for everything",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
@@ -13,17 +13,18 @@
 	"scripts": {
 		"build": "run-s _clean _links _tsc",
 		"test": "node x/tests.test.js",
+		"test-watch": "node --watch x/tests.test.js",
+		"test-inspect": "node inspect x/tests.test.js",
 		"count": "find s -path '*/_archive' -prune -o -name '*.ts' -exec wc -l {} +",
-		"start": "run-p _tscw _testw",
+		"watch": "run-p _tscw test-watch",
 		"_clean": "rm -rf x && mkdir x",
 		"_links": "ln -s \"$(realpath node_modules)\" x/node_modules",
 		"_tsc": "tsc",
-		"_tscw": "tsc -w",
-		"_testw": "node --watch x/tests.test.js"
+		"_tscw": "tsc -w"
 	},
 	"devDependencies": {
-		"@e280/science": "^0.0.4",
-		"@types/node": "^22.15.21",
+		"@e280/science": "^0.0.5",
+		"@types/node": "^22.15.23",
 		"npm-run-all": "^4.1.5",
 		"typescript": "^5.8.3"
 	},

package/s/data/base-x.ts

@@ -0,0 +1,170 @@
+
+import {Bytes} from "./bytes.js"
+
+export type Lexicon = {
+	characters: string
+	negativePrefix?: string
+	padding?: {
+		character: string
+		size: number
+	}
+}
+
+export class BaseX {
+	static lexicons = Object.freeze({
+		base2: {characters: "01"},
+		hex: {characters: "0123456789abcdef"},
+		base36: {characters: "0123456789abcdefghijklmnopqrstuvwxyz"},
+		base58: {characters: "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"},
+		base62: {characters: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"},
+		base64url: {
+			negativePrefix: "~",
+			characters: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_",
+		},
+		base64: {
+			characters: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/",
+			padding: {character: "=", size: 4},
+		},
+	})
+
+	private lookup: Record<string, number>
+	private negativePrefix: string
+
+	constructor(public lexicon: Lexicon) {
+		this.lookup = Object.fromEntries(
+			[...lexicon.characters].map((char, i) => [char, i])
+		)
+		this.negativePrefix = lexicon.negativePrefix ?? "-"
+	}
+
+	toBytes(s: string): Uint8Array {
+		const bitsPerChar = Math.log2(this.lexicon.characters.length)
+		if (Number.isInteger(bitsPerChar)) {
+			// Bitstream mode (for power-of-2 lexicons)
+			let bitBuffer = 0
+			let bitCount = 0
+			const output: number[] = []
+
+			for (const char of s) {
+				if (char === this.lexicon.padding?.character) continue
+				const val = this.lookup[char]
+				if (val === undefined) throw new Error(`Invalid character: ${char}`)
+				bitBuffer = (bitBuffer << bitsPerChar) | val
+				bitCount += bitsPerChar
+
+				while (bitCount >= 8) {
+					bitCount -= 8
+					output.push((bitBuffer >> bitCount) & 0xFF)
+				}
+			}
+
+			return new Uint8Array(output)
+		}
+
+		// Radix mode fallback
+		let num = 0n
+		const base = BigInt(this.lexicon.characters.length)
+		let negative = false
+		if (s.startsWith(this.negativePrefix)) {
+			s = s.slice(this.negativePrefix.length)
+			negative = true
+		}
+		for (const char of s) {
+			const val = this.lookup[char]
+			if (val === undefined) throw new Error(`Invalid character: ${char}`)
+			num = num * base + BigInt(val)
+		}
+		const out: number[] = []
+		while (num > 0n) {
+			out.unshift(Number(num % 256n))
+			num = num / 256n
+		}
+		return new Uint8Array(out)
+	}
+
+	fromBytes(bytes: Uint8Array): string {
+		const bitsPerChar = Math.log2(this.lexicon.characters.length)
+		if (Number.isInteger(bitsPerChar)) {
+			// Bitstream mode (for power-of-2 lexicons)
+			let bitBuffer = 0
+			let bitCount = 0
+			let out = ""
+
+			for (const byte of bytes) {
+				bitBuffer = (bitBuffer << 8) | byte
+				bitCount += 8
+
+				while (bitCount >= bitsPerChar) {
+					bitCount -= bitsPerChar
+					const index = (bitBuffer >> bitCount) & ((1 << bitsPerChar) - 1)
+					out += this.lexicon.characters[index]
+				}
+			}
+
+			// 🩹 flush remaining bits
+			if (bitCount > 0) {
+				const index = (bitBuffer << (bitsPerChar - bitCount)) & ((1 << bitsPerChar) - 1)
+				out += this.lexicon.characters[index]
+			}
+
+			// Add padding if applicable
+			if (this.lexicon.padding) {
+				while (out.length % this.lexicon.padding.size !== 0)
+					out += this.lexicon.padding.character
+			}
+
+			return out
+		}
+
+		// Radix mode fallback
+		let num = 0n
+		for (const byte of bytes)
+			num = (num << 8n) + BigInt(byte)
+
+		if (num === 0n) return this.lexicon.characters[0]
+
+		const base = BigInt(this.lexicon.characters.length)
+		let out = ""
+		while (num > 0n) {
+			out = this.lexicon.characters[Number(num % base)] + out
+			num = num / base
+		}
+		return out
+	}
+
+	toInteger(s: string) {
+		if (!s) return 0
+		let n = 0n
+		let negative = false
+		const base = BigInt(this.lexicon.characters.length)
+		if (s.startsWith(this.negativePrefix)) {
+			s = s.slice(this.negativePrefix.length)
+			negative = true
+		}
+		for (const char of s) {
+			const value = this.lookup[char]
+			if (value === undefined) throw new Error(`Invalid character: ${char}`)
+			n = n * base + BigInt(value)
+		}
+		return Number(negative ? -n : n)
+	}
+
+	fromInteger(n: number) {
+		n = Math.floor(n)
+		const negative = n < 0
+		let num = BigInt(negative ? -n : n)
+		if (num === 0n) return this.lexicon.characters[0]
+		const base = BigInt(this.lexicon.characters.length)
+		let out = ""
+		while (num > 0n) {
+			out = this.lexicon.characters[Number(num % base)] + out
+			num = num / base
+		}
+		return negative ? `${this.negativePrefix}${out}` : out
+	}
+
+	random(count = 32) {
+		return this.fromBytes(Bytes.random(count))
+	}
+}
+

package/s/data/base58.ts

@@ -16,8 +16,8 @@ const base = 58
 const characters = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
 
 export const Base58 = Object.freeze({
-	string(bytes: Uint8Array) {
-		let intVal = BigInt("0x" + Hex.string(bytes))
+	fromBytes(bytes: Uint8Array) {
+		let intVal = BigInt("0x" + Hex.fromBytes(bytes))
 		let encoded = ""
 
 		while (intVal > 0) {
@@ -34,7 +34,7 @@ export const Base58 = Object.freeze({
 		return encoded
 	},
 
-	bytes(string: string) {
+	toBytes(string: string) {
 		let intVal = BigInt(0)
 
 		for (const char of string) {
@@ -45,7 +45,7 @@ export const Base58 = Object.freeze({
 
 		let hex = intVal.toString(16)
 		if (hex.length % 2 !== 0) hex = "0" + hex
-		const bytes = Hex.bytes(hex)
+		const bytes = Hex.toBytes(hex)
 
 		let leadingZeroes = 0
 		for (const char of string) {
@@ -59,7 +59,17 @@ export const Base58 = Object.freeze({
 	},
 
 	random(count = 32) {
-		return this.string(Bytes.random(count))
+		return this.fromBytes(Bytes.random(count))
+	},
+
+	/** @deprecated renamed to `fromBytes` */
+	string(bytes: Uint8Array) {
+		return Base58.fromBytes(bytes)
+	},
+
+	/** @deprecated renamed to `toBytes` */
+	bytes(string: string) {
+		return Base58.toBytes(string)
 	},
 })
 

package/s/data/base64.ts

@@ -1,22 +1,31 @@
 
 import {Bytes} from "./bytes.js"
 
-export const Base64 = {
-
-	string(bytes: Uint8Array) {
+export const Base64 = Object.freeze({
+	fromBytes(bytes: Uint8Array) {
 		return (typeof btoa === "function")
 			? btoa(String.fromCharCode(...bytes))
 			: Buffer.from(bytes).toString("base64")
 	},
 
-	bytes(string: string) {
+	toBytes(string: string) {
 		return (typeof atob === "function")
 			? Uint8Array.from(atob(string), char => char.charCodeAt(0))
 			: Uint8Array.from(Buffer.from(string, "base64"))
 	},
 
 	random(count = 32) {
-		return this.string(Bytes.random(count))
+		return this.fromBytes(Bytes.random(count))
+	},
+
+	/** @deprecated rename to "fromBytes" */
+	string(bytes: Uint8Array) {
+		return Base64.fromBytes(bytes)
+	},
+
+	/** @deprecated rename to "toBytes" */
+	bytes(string: string) {
+		return Base64.toBytes(string)
 	},
-}
+})
 

package/s/data/base64url.ts

@@ -3,25 +3,34 @@ import {Bytes} from "./bytes.js"
 import {Base64} from "./base64.js"
 
 export const Base64url = {
-
-	string(bytes: Uint8Array) {
-		return Base64.string(bytes)
+	fromBytes(bytes: Uint8Array) {
+		return Base64.fromBytes(bytes)
 			.replace(/\+/g, "-")
 			.replace(/\//g, "_")
 			.replace(/=+$/g, "")
 	},
 
-	bytes(string: string) {
+	toBytes(string: string) {
 		let b64 = string
 			.replace(/-/g, "+")
 			.replace(/_/g, "/")
 		if (b64.length % 4 !== 0)
 			b64 = b64.padEnd(b64.length + (4 - b64.length % 4) % 4, "=")
-		return Base64.bytes(b64)
+		return Base64.toBytes(b64)
 	},
 
 	random(count = 32) {
-		return this.string(Bytes.random(count))
+		return this.fromBytes(Bytes.random(count))
+	},
+
+	/** @deprecated renamed to "fromBytes" */
+	string(bytes: Uint8Array) {
+		return Base64url.fromBytes(bytes)
+	},
+
+	/** @deprecated renamed to "toBytes" */
+	bytes(string: string) {
+		return Base64url.toBytes(string)
 	},
 }
 

package/s/data/bytename/bytename.ts

@@ -80,11 +80,11 @@ export const Bytename = {
 	},
 
 	toHex(bytename: string) {
-		return Hex.string(Bytename.toBytes(bytename))
+		return Hex.fromBytes(Bytename.toBytes(bytename))
 	},
 
 	fromHex(hex: string, options?: Partial<BytenameOptions>) {
-		return Bytename.fromBytes(Hex.bytes(hex), options)
+		return Bytename.fromBytes(Hex.toBytes(hex), options)
 	},
 }
 

package/s/data/bytename/thumbprint.test.ts

@@ -6,7 +6,7 @@ import {Thumbprint} from "./thumbprint.js"
 
 const sampleThumbprint = "nodlyn.fasrep.habbud.ralwel.Avo7gFmdWMRHkwsD149mcaBoZdS69iXuJ"
 const sampleHex = "88e8c3fad1028fcf6ce5ac491578850f4d833336feca03b608265501c3019d59"
-const sampleBytes = Hex.bytes(sampleHex)
+const sampleBytes = Hex.toBytes(sampleHex)
 
 function good(bytes: Uint8Array) {
 	expect(Bytes.eq(bytes, sampleBytes)).ok()

package/s/data/bytename/thumbprint.ts

@@ -46,7 +46,7 @@ export const Thumbprint = {
 
 		return new Uint8Array([
 			...Bytename.toBytes(preview),
-			...Base58.bytes(bulk),
+			...Base58.toBytes(bulk),
 		])
 	},
 
@@ -71,7 +71,7 @@ export const Thumbprint = {
 			const preview = yoink(previewBytes)
 
 			const bulk = (bytes.length > previewBytes)
-				? Base58.string(bytes.slice(previewBytes))
+				? Base58.fromBytes(bytes.slice(previewBytes))
 				: ""
 
 			const thumbprint = [preview, bulk]
@@ -82,14 +82,14 @@ export const Thumbprint = {
 		},
 
 		fromHex(hex: string, options?: Partial<ThumbprintOptions>) {
-			const bytes = Hex.bytes(hex)
+			const bytes = Hex.toBytes(hex)
 			return Thumbprint.build.fromBytes(bytes, options)
 		},
 	},
 
 	toHex(thumbprint: string) {
 		const bytes = Thumbprint.toBytes(thumbprint)
-		return Hex.string(bytes)
+		return Hex.fromBytes(bytes)
 	},
 
 	fromBytes(bytes: Uint8Array, options?: Partial<ThumbprintOptions>) {
@@ -97,7 +97,7 @@ export const Thumbprint = {
 	},
 
 	fromHex(hex: string, options?: Partial<ThumbprintOptions>) {
-		return Thumbprint.fromBytes(Hex.bytes(hex), options)
+		return Thumbprint.fromBytes(Hex.toBytes(hex), options)
 	},
 
 	sigil: {

package/s/data/bytes.ts

@@ -1,5 +1,5 @@
 
-export const Bytes = {
+export const Bytes = Object.freeze({
 	eq(a: Uint8Array, b: Uint8Array) {
 		if (a.length !== b.length)
 			return false
@@ -13,5 +13,5 @@ export const Bytes = {
 	random(count: number) {
 		return crypto.getRandomValues(new Uint8Array(count))
 	},
-}
+})
 

package/s/data/data.test.ts

@@ -0,0 +1,98 @@
+
+import {Science, test, expect} from "@e280/science"
+import {ob} from "../ob.js"
+import {Txt} from "./txt.js"
+import {Hex} from "./hex.js"
+import {Bytes} from "./bytes.js"
+import {BaseX} from "./base-x.js"
+import {Base58} from "./base58.js"
+import {Base64} from "./base64.js"
+import {Base64url} from "./base64url.js"
+
+const sampleBytes = Hex.toBytes("9960cd633a46acfe8307d8a400e842da0d930a75fb8188e0f5da264e4b6b4e5b")
+
+type ByteUtil = {
+	toBytes: (string: string) => Uint8Array
+	fromBytes: (bytes: Uint8Array) => string
+}
+
+type NumberUtil = {
+	toInteger: (s: string) => number
+	fromInteger: (n: number) => string
+}
+
+function testBytes(util: ByteUtil) {
+	return async() => {
+		const string = util.fromBytes(sampleBytes)
+		const recreated = util.toBytes(string)
+		expect(Bytes.eq(sampleBytes, recreated)).ok()
+	}
+}
+
+function testNumbers(util: NumberUtil) {
+	return {
+		positive: async() => {
+			const original = 123456789
+			const string = util.fromInteger(original)
+			const recreated = util.toInteger(string)
+			expect(original).is(recreated)
+			expect(util.toInteger("")).is(0)
+		},
+		negative: async() => {
+			const original = -123456789
+			const string = util.fromInteger(original)
+			const recreated = util.toInteger(string)
+			expect(original).is(recreated)
+			expect(util.toInteger("")).is(0)
+		},
+	}
+}
+
+function testBoth(util: ByteUtil & NumberUtil) {
+	return {
+		bytes: testBytes(util),
+		numbers: testNumbers(util),
+	}
+}
+
+function testCompat(alpha: ByteUtil, bravo: ByteUtil) {
+	return async() => {
+		expect(alpha.fromBytes(sampleBytes))
+			.is(bravo.fromBytes(sampleBytes))
+	}
+}
+
+export default Science.suite({
+	"Base58": testBytes(Base58),
+	"Base64": testBytes(Base64),
+	"Base64url": testBytes(Base64url),
+	"Hex": testBytes(Hex),
+
+	"Txt": test(async() => {
+		const original = `build or die. 💻>☠️ 命火工`
+		const bytes = Txt.toBytes(original)
+		const recreated = Txt.fromBytes(bytes)
+		expect(original).is(recreated)
+	}),
+
+	"BaseX": Science.suite({
+		lexicons: Science.suite(
+			ob(BaseX.lexicons).map(lex => testBoth(new BaseX(lex)))
+		),
+		compat: Science.suite({
+			"Hex": testCompat(Hex, new BaseX(BaseX.lexicons.hex)),
+			"Base64": testCompat(Base64, new BaseX(BaseX.lexicons.base64)),
+			"Base64url": testCompat(Base64url, new BaseX(BaseX.lexicons.base64url)),
+		}),
+		"base64 has padding": test(async() => {
+			const s = new BaseX(BaseX.lexicons.base64).fromBytes(sampleBytes)
+			expect(s.endsWith("=")).ok()
+		}),
+		"antagonistic base64 positive integer": test(async() => {
+			const base64url = new BaseX(BaseX.lexicons.base64url)
+			expect(base64url.toInteger(base64url.fromInteger(62))).is(62)
+			expect(base64url.toInteger(base64url.fromInteger(4030))).is(4030)
+		}),
+	}),
+})
+

package/s/data/hex.ts

@@ -11,14 +11,14 @@
 
 import {Bytes} from "./bytes.js"
 
-export const Hex = {
-	string(bytes: Uint8Array) {
+export const Hex = Object.freeze({
+	fromBytes(bytes: Uint8Array) {
 		return [...bytes]
 			.map(byte => byte.toString(16).padStart(2, "0"))
 			.join("")
 	},
 
-	bytes(string: string) {
+	toBytes(string: string) {
 		if (string.length % 2 !== 0)
 			throw new Error("must have even number of hex characters")
 		const bytes = new Uint8Array(string.length / 2)
@@ -29,7 +29,17 @@ export const Hex = {
 
 	/** generate a random hex string. byteCount defaults to 32. */
 	random(byteCount = 32) {
-		return this.string(Bytes.random(byteCount))
+		return this.fromBytes(Bytes.random(byteCount))
+	},
+
+	/** @deprecated renamed to `fromBytes` */
+	string(bytes: Uint8Array) {
+		return Hex.fromBytes(bytes)
+	},
+
+	/** @deprecated renamed to `toBytes` */
+	bytes(string: string) {
+		return Hex.toBytes(string)
 	},
-}
+})
 

package/s/data/txt.ts

@@ -1,11 +1,21 @@
 
-export const Txt = {
-	string(bytes: Uint8Array) {
+export const Txt = Object.freeze({
+	fromBytes(bytes: Uint8Array) {
 		return new TextDecoder().decode(bytes)
 	},
 
-	bytes(string: string) {
+	toBytes(string: string) {
 		return new TextEncoder().encode(string)
 	},
-}
+
+	/** @deprecated renamed to `fromBytes` */
+	string(bytes: Uint8Array) {
+		return Txt.fromBytes(bytes)
+	},
+
+	/** @deprecated renamed to `toBytes` */
+	bytes(string: string) {
+		return Txt.toBytes(string)
+	},
+})
 

package/s/index.ts

@@ -1,5 +1,6 @@
 
 export * from "./data/bytename/index.js"
+export * from "./data/base-x.js"
 export * from "./data/base58.js"
 export * from "./data/base64.js"
 export * from "./data/base64url.js"

package/s/tests.test.ts

@@ -1,17 +1,19 @@
 
 import {Science} from "@e280/science"
 
-import cloneTest from "./clone/clone.test.js"
-import thumbprintTest from "./data/bytename/thumbprint.test.js"
-import debounceTest from "./debounce/debounce.test.js"
-import bytenameTest from "./data/bytename/bytename.test.js"
-import deepTest from "./deep/deep.test.js"
+import clone from "./clone/clone.test.js"
+import thumbprint from "./data/bytename/thumbprint.test.js"
+import debounce from "./debounce/debounce.test.js"
+import bytename from "./data/bytename/bytename.test.js"
+import deep from "./deep/deep.test.js"
+import data from "./data/data.test.js"
 
 await Science.run({
-	clone: cloneTest,
-	bytename: bytenameTest,
-	thumbprint: thumbprintTest,
-	debounce: debounceTest,
-	deep: deepTest,
+	clone,
+	bytename,
+	thumbprint,
+	debounce,
+	deep,
+	data,
 })