@e280/stz 0.0.0-3 → 0.0.0-31

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.test.ts

@@ -0,0 +1,49 @@
+
+import {Bytes} from "../bytes.js"
+import {Bytename} from "./bytename.js"
+import {Science, test, expect} from "@e280/science"
+
+const deadbeef = new Uint8Array([0xDE, 0xAD, 0xBE, 0xEF])
+
+function good(bytes: Uint8Array) {
+	expect(Bytes.eq(bytes, deadbeef)).ok()
+}
+
+export default Science.suite({
+	"bytes->string->bytes": test(async() => {
+		const text = Bytename.fromBytes(deadbeef)
+		expect(text).is("ribmug.hilmun")
+		good(Bytename.toBytes(text))
+	}),
+
+	"zero bytes": test(async() => {
+		const text = Bytename.fromBytes(new Uint8Array([]))
+		expect(text).is("")
+	}),
+
+	"one byte": test(async() => {
+		const text = Bytename.fromBytes(new Uint8Array([0x00]))
+		expect(text).is("doz")
+	}),
+
+	"groupings": test(async() => {
+		const bytes = new Uint8Array([...deadbeef, ...deadbeef])
+		const text = Bytename.fromBytes(bytes, {
+			groupSize: 2,
+			groupSeparator: " ",
+			wordSeparator: ".",
+		})
+		expect(text).is("ribmug.hilmun ribmug.hilmun")
+	}),
+
+	"wordsep": Science.suite({
+		"underscore": test(async() => good(Bytename.toBytes("ribmug_hilmun"))),
+		"uppercase": test(async() => good(Bytename.toBytes("RIBMUG_HILMUN"))),
+		"dots": test(async() => good(Bytename.toBytes("ribmug.hilmun"))),
+		"crushed": test(async() => good(Bytename.toBytes("ribmughilmun"))),
+		"space": test(async() => good(Bytename.toBytes("ribmug hilmun"))),
+		"spaces": test(async() => good(Bytename.toBytes("ribmug  hilmun"))),
+		"whitespace": test(async() => good(Bytename.toBytes("\n ribmug \n \t \n hilmun \n"))),
+	}),
+})
+

package/s/data/{barname/barname.ts → bytename/bytename.ts}

@@ -1,19 +1,39 @@
 
+import {Hex} from "../hex.js"
 import {Bytes} from "../bytes.js"
 import {prefixes} from "./utils/prefixes.js"
 import {suffixes} from "./utils/suffixes.js"
 
-const wordSeparator = "_"
-const groupSeparator = " "
-const defaultWordsPerGroup = 4
+export type BytenameOptions = {
+	groupSize: number
+	wordSeparator: string
+	groupSeparator: string
+}
+
+/**
+ * Bytename is a friendly presentation format for arbitrary binary data.
+ *  - looks like "midsen.picmyn.widrep.baclut dotreg.filtyp.nosnus.siptev"
+ *  - each byte maps to a three-letter triplet
+ *  - all delimiters are just sugar, parser doesn't care
+ */
+export const Bytename = {
+	defaults: (<BytenameOptions>{
+		groupSize: 4,
+		wordSeparator: ".",
+		groupSeparator: " ",
+	}),
 
-export const Barname = {
-	random(byteCount: number) {
-		return this.string(Bytes.random(byteCount))
+	random(byteCount: number, options?: Partial<BytenameOptions>) {
+		const bytes = Bytes.random(byteCount)
+		return this.fromBytes(bytes, options)
 	},
 
-	string(bytes: Uint8Array, options?: {wordsPerGroup?: number}) {
-		const groupSize = options?.wordsPerGroup ?? defaultWordsPerGroup
+	fromBytes(bytes: Uint8Array, options: Partial<BytenameOptions> = {}) {
+		const {
+			groupSize = Bytename.defaults.groupSize,
+			wordSeparator = Bytename.defaults.wordSeparator,
+			groupSeparator = Bytename.defaults.groupSeparator,
+		} = options
 
 		const words: string[] = []
 		let currentWord: string[] = []
@@ -37,8 +57,8 @@ export const Barname = {
 		return grouped.join(groupSeparator)
 	},
 
-	bytes(string: string) {
-		const letters = string
+	toBytes(bytename: string) {
+		const letters = bytename
 			.toLowerCase()
 			.replace(/[^a-z]/g, "") // strip everything except letters
 
@@ -58,5 +78,13 @@ export const Barname = {
 			return number
 		}))
 	},
+
+	toHex(bytename: string) {
+		return Hex.fromBytes(Bytename.toBytes(bytename))
+	},
+
+	fromHex(hex: string, options?: Partial<BytenameOptions>) {
+		return Bytename.fromBytes(Hex.toBytes(hex), options)
+	},
 }
 

package/s/data/bytename/index.ts

@@ -0,0 +1,4 @@
+
+export * from "./bytename.js"
+export * from "./thumbprint.js"
+

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

@@ -0,0 +1,53 @@
+
+import {Science, test, expect} from "@e280/science"
+import {Hex} from "../hex.js"
+import {Bytes} from "../bytes.js"
+import {Thumbprint} from "./thumbprint.js"
+
+const sampleThumbprint = "nodlyn.fasrep.habbud.ralwel.Avo7gFmdWMRHkwsD149mcaBoZdS69iXuJ"
+const sampleHex = "88e8c3fad1028fcf6ce5ac491578850f4d833336feca03b608265501c3019d59"
+const sampleBytes = Hex.toBytes(sampleHex)
+
+function good(bytes: Uint8Array) {
+	expect(Bytes.eq(bytes, sampleBytes)).ok()
+}
+
+export default Science.suite({
+	"bytes->string->bytes": test(async() => {
+		const text = Thumbprint.fromBytes(sampleBytes)
+		expect(text).is(sampleThumbprint)
+		good(Thumbprint.toBytes(text))
+	}),
+
+	"zero bytes": test(async() => {
+		const text = Thumbprint.fromBytes(new Uint8Array([]))
+		expect(text).is("")
+		expect(Bytes.eq(Thumbprint.toBytes(text), new Uint8Array([]))).ok()
+	}),
+
+	"one byte": test(async() => {
+		const text = Thumbprint.fromBytes(new Uint8Array([0x00]))
+		expect(text).is("doz")
+		expect(Bytes.eq(Thumbprint.toBytes(text), new Uint8Array([0x00]))).ok()
+	}),
+
+	"partially": Science.suite({
+		"normal": test(async() => expect(Thumbprint.toBytes(sampleThumbprint).length).ok()),
+		"nothing": test(async() => expect(Thumbprint.toBytes("").length).is(0)),
+		"no-bulk": test(async() => expect(Thumbprint.toBytes("nodlyn.fasrep").length).ok()),
+		"one-byte": test(async() => expect(Thumbprint.toBytes("nod").length).is(1)),
+		"three-byte": test(async() => expect(Thumbprint.toBytes("nodlynfas").length).is(3)),
+		"one-byte-sigil": test(async() => expect(Thumbprint.toBytes("nod::39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k").length).ok()),
+	}),
+
+	"tolerance": Science.suite({
+		"normal": test(async() => good(Thumbprint.toBytes("nodlyn.fasrep::39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k"))),
+		"coolio": test(async() => good(Thumbprint.toBytes("nodlyn.fasrep..39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k"))),
+		"spaces": test(async() => good(Thumbprint.toBytes("nodlyn fasrep 39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k"))),
+		"dots": test(async() => good(Thumbprint.toBytes("nodlyn.fasrep.39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k"))),
+		"one-space": test(async() => good(Thumbprint.toBytes("nodlynfasrep 39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k"))),
+		"one-newline": test(async() => good(Thumbprint.toBytes("nodlynfasrep\n39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k"))),
+		"whitespace": test(async() => good(Thumbprint.toBytes("\t\n nodlyn\n fasrep \n\n\t\n 39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k\n\t"))),
+	}),
+})
+

package/s/data/bytename/thumbprint.ts

@@ -0,0 +1,112 @@
+
+import {Hex} from "../hex.js"
+import {Base58} from "../base58.js"
+import {Bytename} from "./bytename.js"
+
+export type ThumbprintOptions = {
+	delimiter: string
+	sigilBytes: number
+	previewBytes: number
+}
+
+export type ThumbprintData = {
+	bytes: Uint8Array
+	thumbprint: string
+	preview: string
+	bulk: string
+	sigil: string
+}
+
+/**
+ * Thumbprint is a friendly presentation format for arbitrary binary data.
+ *  - looks like "nodlyn.fasrep.habbud.ralwel.Avo7gFmdWMRHkwsD149mcaBoZdS69iXuJ"
+ *  - the preview: "nodlyn.fasrep.habbud.ralwel" (bytename format)
+ *  - the bulk: "Avo7gFmdWMRHkwsD149mcaBoZdS69iXuJ" (base58 format)
+ *  - the sigil: "nodlyn.fasrep" (shorter part of the bytename)
+ *  - originally designed to be a nice way to present 256-bit ids, but can actually represent any number of bytes
+ */
+export const Thumbprint = {
+	defaults: (<ThumbprintOptions>{
+		delimiter: ".",
+		sigilBytes: 4,
+		previewBytes: 8,
+	}),
+
+	toBytes(thumbprint: string) {
+		thumbprint = thumbprint.trim()
+		const beans = thumbprint.split(/[^a-zA-Z0-9]+/m)
+			.filter(Boolean)
+			.map(s => s.trim())
+
+		if (beans.length < 2)
+			return Bytename.toBytes(beans.join(""))
+
+		const bulk = beans.pop()!
+		const preview = beans.join("")
+
+		return new Uint8Array([
+			...Bytename.toBytes(preview),
+			...Base58.toBytes(bulk),
+		])
+	},
+
+	parse(thumbprint: string, options?: Partial<ThumbprintOptions>): ThumbprintData {
+		const bytes = Thumbprint.toBytes(thumbprint)
+		return Thumbprint.build.fromBytes(bytes, options)
+	},
+
+	build: {
+		fromBytes(bytes: Uint8Array, options: Partial<ThumbprintOptions> = {}): ThumbprintData {
+			const {delimiter, previewBytes, sigilBytes}
+				= {...Thumbprint.defaults, ...options}
+
+			const yoink = (b: number) => (bytes.length > 0)
+				? Bytename.fromBytes(bytes.slice(0, b), {
+					wordSeparator: delimiter,
+					groupSeparator: delimiter,
+				})
+				: ""
+
+			const sigil = yoink(sigilBytes)
+			const preview = yoink(previewBytes)
+
+			const bulk = (bytes.length > previewBytes)
+				? Base58.fromBytes(bytes.slice(previewBytes))
+				: ""
+
+			const thumbprint = [preview, bulk]
+				.filter(s => s.length > 0)
+				.join(delimiter)
+
+			return {bytes, thumbprint, preview, bulk, sigil}
+		},
+
+		fromHex(hex: string, options?: Partial<ThumbprintOptions>) {
+			const bytes = Hex.toBytes(hex)
+			return Thumbprint.build.fromBytes(bytes, options)
+		},
+	},
+
+	toHex(thumbprint: string) {
+		const bytes = Thumbprint.toBytes(thumbprint)
+		return Hex.fromBytes(bytes)
+	},
+
+	fromBytes(bytes: Uint8Array, options?: Partial<ThumbprintOptions>) {
+		return Thumbprint.build.fromBytes(bytes, options).thumbprint
+	},
+
+	fromHex(hex: string, options?: Partial<ThumbprintOptions>) {
+		return Thumbprint.fromBytes(Hex.toBytes(hex), options)
+	},
+
+	sigil: {
+		fromHex(hex: string, options?: Partial<ThumbprintOptions>) {
+			return Thumbprint.build.fromHex(hex, options).sigil
+		},
+		fromBytes(bytes: Uint8Array, options?: Partial<ThumbprintOptions>) {
+			return Thumbprint.build.fromBytes(bytes, options).sigil
+		},
+	},
+}
+

package/s/data/bytes.ts

@@ -1,7 +1,17 @@
 
-export const Bytes = {
+export const Bytes = Object.freeze({
+	eq(a: Uint8Array, b: Uint8Array) {
+		if (a.length !== b.length)
+			return false
+		for (let i = 0; i <= a.length; i++) {
+			if (a.at(i) !== b.at(i))
+				return false
+		}
+		return true
+	},
+
 	random(count: number) {
 		return crypto.getRandomValues(new Uint8Array(count))
 	},
-}
+})