@e280/stz 0.0.0-8 → 0.0.0

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

@@ -11,24 +11,24 @@ function good(bytes: Uint8Array) {
 
 export default Science.suite({
 	"bytes->string->bytes": test(async() => {
-		const text = Bytename.string(deadbeef)
+		const text = Bytename.fromBytes(deadbeef)
 		expect(text).is("ribmug.hilmun")
-		good(Bytename.bytes(text))
+		good(Bytename.toBytes(text))
 	}),
 
 	"zero bytes": test(async() => {
-		const text = Bytename.string(new Uint8Array([]))
+		const text = Bytename.fromBytes(new Uint8Array([]))
 		expect(text).is("")
 	}),
 
 	"one byte": test(async() => {
-		const text = Bytename.string(new Uint8Array([0x00]))
+		const text = Bytename.fromBytes(new Uint8Array([0x00]))
 		expect(text).is("doz")
 	}),
 
 	"groupings": test(async() => {
 		const bytes = new Uint8Array([...deadbeef, ...deadbeef])
-		const text = Bytename.string(bytes, {
+		const text = Bytename.fromBytes(bytes, {
 			groupSize: 2,
 			groupSeparator: " ",
 			wordSeparator: ".",
@@ -37,13 +37,13 @@ export default Science.suite({
 	}),
 
 	"wordsep": Science.suite({
-		"underscore": test(async() => good(Bytename.bytes("ribmug_hilmun"))),
-		"uppercase": test(async() => good(Bytename.bytes("RIBMUG_HILMUN"))),
-		"dots": test(async() => good(Bytename.bytes("ribmug.hilmun"))),
-		"crushed": test(async() => good(Bytename.bytes("ribmughilmun"))),
-		"space": test(async() => good(Bytename.bytes("ribmug hilmun"))),
-		"spaces": test(async() => good(Bytename.bytes("ribmug  hilmun"))),
-		"whitespace": test(async() => good(Bytename.bytes("\n ribmug \n \t \n hilmun \n"))),
+		"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/bytename/bytename.ts

@@ -10,6 +10,12 @@ export type BytenameOptions = {
 	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,
@@ -18,10 +24,11 @@ export const Bytename = {
 	}),
 
 	random(byteCount: number, options?: Partial<BytenameOptions>) {
-		return this.string(Bytes.random(byteCount), options)
+		const bytes = Bytes.random(byteCount)
+		return this.fromBytes(bytes, options)
 	},
 
-	string(bytes: Uint8Array, options: Partial<BytenameOptions> = {}) {
+	fromBytes(bytes: Uint8Array, options: Partial<BytenameOptions> = {}) {
 		const {
 			groupSize = Bytename.defaults.groupSize,
 			wordSeparator = Bytename.defaults.wordSeparator,
@@ -50,7 +57,7 @@ export const Bytename = {
 		return grouped.join(groupSeparator)
 	},
 
-	bytes(bytename: string) {
+	toBytes(bytename: string) {
 		const letters = bytename
 			.toLowerCase()
 			.replace(/[^a-z]/g, "") // strip everything except letters
@@ -72,12 +79,12 @@ export const Bytename = {
 		}))
 	},
 
-	hex(bytename: string) {
-		return Hex.string(Bytename.bytes(bytename))
+	toHex(bytename: string) {
+		return Hex.fromBytes(Bytename.toBytes(bytename))
 	},
 
 	fromHex(hex: string, options?: Partial<BytenameOptions>) {
-		return Bytename.string(Hex.bytes(hex), options)
+		return Bytename.fromBytes(Hex.toBytes(hex), options)
 	},
 }
 

package/s/data/bytename/index.ts

@@ -1,4 +1,4 @@
 
 export * from "./bytename.js"
-export * from "./badge.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,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/deadline.ts

@@ -1,26 +1,25 @@
 
 export class DeadlineError extends Error {
 	name = this.constructor.name
-	constructor(public milliseconds: number, message: string) {
-		super(`${message}, timed out in ${(milliseconds / 1000).toFixed(1)} seconds`)
+	constructor(public milliseconds: number) {
+		super(`deadline exceeded (${(milliseconds / 1000).toFixed(1)} seconds)`)
 	}
 }
 
 /** set a deadline for a fn to do something, will reject with a `DeadlineError` if it takes too long */
-export function deadline<R>(milliseconds: number, message: string, fn: () => Promise<R>) {
+export function deadline<R>(milliseconds: number, fn: () => Promise<R>) {
 	if (milliseconds <= 0 || milliseconds === Infinity)
 		return fn()
 
 	return new Promise<R>((resolve, reject) => {
-
 		const id = setTimeout(
-			() => reject(new DeadlineError(milliseconds, message)),
+			() => reject(new DeadlineError(milliseconds)),
 			milliseconds,
 		)
-
 		fn()
 			.then(resolve)
 			.catch(reject)
 			.finally(() => clearTimeout(id))
 	})
 }
+

package/s/{defer-promise.ts → defer.ts}

@@ -1,6 +1,6 @@
 
 /** a promise which can be resolved from the outside */
-export type DeferredPromise<R> = {
+export type Deferred<R = void> = {
 	promise: Promise<R>
 	resolve: (result: R) => void
 	reject: (reason: any) => void
@@ -10,7 +10,7 @@ export type DeferredPromise<R> = {
 }
 
 /** returns a deferred promise with exposed resolve and reject fns */
-export function deferPromise<R>(): DeferredPromise<R> {
+export function defer<R = void>(): Deferred<R> {
 	let resolve!: (result: R) => void
 	let reject!: (reason: any) => void
 

package/s/drill.ts

@@ -1,9 +1,7 @@
 
 import {is} from "./is.js"
 
-/**
- * return a value within an object tree, found at the given path.
- */
+/** return a value within an object tree, found at the given path. */
 export function drill<xResult>(
 		object: {[key: string]: any},
 		path: string[],
@@ -13,7 +11,7 @@ export function drill<xResult>(
 
 	for (const key of path) {
 		current = current[key]
-		if (is.unavailable(current))
+		if (is.unset(current))
 			break
 	}
 

package/s/ev.ts

@@ -0,0 +1,20 @@
+
+export type EvFn = (...a: any[]) => void
+
+export type EvTarget<N extends string> = {
+	addEventListener(name: N, fn: EvFn): void
+	removeEventListener(name: N, fn: EvFn): void
+}
+
+export function ev<N extends string>(target: EvTarget<N>, fns: Record<N, EvFn>) {
+	const entries = Object.entries(fns) as [N, EvFn][]
+
+	for (const [name, fn] of entries)
+		target.addEventListener(name, fn)
+
+	return () => {
+		for (const [name, fn] of entries)
+			target.removeEventListener(name, fn)
+	}
+}
+

package/s/id-counter.ts

@@ -0,0 +1,9 @@
+
+export class IdCounter {
+	constructor(public count = 0) {}
+
+	next() {
+		return this.count++
+	}
+}
+

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"
@@ -12,20 +13,30 @@ export * from "./debounce/types.js"
 
 export * from "./deep/deep.js"
 
+export * from "./queue/queue.js"
+
 export * from "./coalesce.js"
 export * from "./concurrent.js"
+export * from "./constructor.js"
 export * from "./deadline.js"
 export * from "./dedupe.js"
-export * from "./defer-promise.js"
+export * from "./defer.js"
 export * from "./drill.js"
 export * from "./escape-regex.js"
+export * from "./ev.js"
 export * from "./hat.js"
+export * from "./id-counter.js"
 export * from "./is.js"
 export * from "./loopy.js"
 export * from "./map-g.js"
 export * from "./nap.js"
 export * from "./ob.js"
+export * from "./once.js"
 export * from "./pipe.js"
 export * from "./pubsub.js"
+export * from "./repeat.js"
+export * from "./scope.js"
+export * from "./templating.js"
+export * from "./time.js"
 export * from "./trash.js"
 

package/s/is.ts

@@ -1,9 +1,9 @@
 
-export const is = {
-	available: <X>(x: X): x is NonNullable<X> =>
+export const is = Object.freeze({
+	set: <X>(x: X): x is NonNullable<X> =>
 		x !== undefined && x !== null,
 
-	unavailable: (x: any): x is (undefined | null) =>
+	unset: (x: any): x is (undefined | null) =>
 		x === undefined || x === null,
 
 	boolean: (x: any): x is boolean =>
@@ -23,5 +23,11 @@ export const is = {
 
 	array: (x: any | any[]): x is any[] =>
 		Array.isArray(x),
-}
+
+	fn: (x: any): x is (...a: any[]) => any =>
+		typeof x === "function",
+
+	symbol: (x: any): x is symbol =>
+		typeof x === "symbol",
+})
 

package/s/map-g.ts

@@ -1,22 +1,21 @@
 
-/** js map, but with handy methods like `require` and `guarantee` */
+/** extended js map with handy methods like `require` and `guarantee` */
 export class MapG<K, V> extends Map<K, V> {
 	static require<K, V>(map: Map<K, V>, key: K) {
-		const value = map.get(key)
-		if (value === undefined)
+		if (map.has(key))
+			return map.get(key)!
+		else
 			throw new Error(`required key not found: "${key}"`)
-		return value
 	}
 
 	static guarantee<K, V>(map: Map<K, V>, key: K, make: () => V) {
-		let value = map.get(key)
-
-		if (value === undefined) {
-			value = make()
+		if (map.has(key))
+			return map.get(key)!
+		else {
+			const value = make()
 			map.set(key, value)
+			return value
 		}
-
-		return value
 	}
 
 	array() {

package/s/nap.ts

@@ -1,4 +1,5 @@
 
+/** create a promise that waits for a number of milliseconds. */
 export const nap = (milliseconds: number = 0) => (
 	new Promise<void>(resolve => setTimeout(resolve, milliseconds))
 )

package/s/once.ts

@@ -0,0 +1,14 @@
+
+export function once<Fn extends (...a: any[]) => any>(fn: Fn) {
+	let done = false
+	let ret: any
+
+	return ((...a) => {
+		if (!done) {
+			done = true
+			ret = fn(...a)
+		}
+		return ret
+	}) as Fn
+}
+