@e280/stz 0.0.0-3 → 0.0.0-30

package/README.md

@@ -0,0 +1,170 @@
+
+# `@e280/stz`
+standard library of environment-agnostic typescript functions we use basically everywhere
+- zero dependencies
+
+<br/>
+
+## MapG
+### extended js map
+- `map.require`
+  ```ts
+  import {MapG} from "@e280/stz"
+
+  const map = new MapG<number, string>([
+    [1, "hello"],
+    [2, "world"],
+  ])
+
+  // throws error if the value is undefined
+  const value = map.require(1)
+  ```
+- `map.guarantee`
+  ```ts
+  // if the value is undefined, the new value "rofl" is set and returned
+  const value = map.guarantee(3, () => "rofl")
+  ```
+
+<br/>
+
+## pub and sub
+### ergonomic event emitters
+- make a publisher fn
+  ```ts
+  import {pub} from "@e280/stz"
+
+  // create a pub fn
+  const sendMessage = pub<[string]>()
+
+  // subscribe to it
+  sendMessage.sub(m => console.log(m))
+
+  // publish to it
+  sendMessage("hello")
+  ```
+- make a subscriber fn *(see how it's just the reverse of pub?)*
+  ```ts
+  import {sub} from "@e280/stz"
+
+  // create a sub fn
+  const onMessage = sub<[string]>()
+
+  // subscribe to it
+  onMessage(m => console.log(m))
+
+  // publish to it
+  onMessage.pub("hello")
+  ```
+- the pub and sub are the same, but have differing invoke signatures
+- i seem to use `sub` more often
+- both have some extra functionality
+  ```ts
+  // pub fns return a promise, to wait for all async subscribers
+  await sendMessage("hello")
+  await onMessage.pub("hello")
+
+  // sub fns return an unsub fn
+  const unsub1 = onMessage(m => console.log(m))
+  unsub1() // unsubscribe that listener
+
+  const unsub2 = sendMessage.sub(m => console.log(m))
+  unsub2() // unsubscribe that listener
+
+  // you can clear all subscribers from a pub or a sub
+  sendMessage.clear()
+  onMessage.clear()
+
+  // instead of a 'once' fn we simply await next()
+  await onMessage.next()
+  await sendMessage.next()
+  ```
+
+<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
+
+a bytename looks like `"midsen.picmyn.widrep.baclut dotreg.filtyp.nosnus.siptev"`. that's 16 bytes. each byte maps to a three-letter triplet
+
+the bytename parser (`Bytename.toBytes`) ignores all non-alphabetic characters. thus `midsen.picmyn`, `midsenpicmyn`, and `mid@sen$pic@myn` are all equal.
+
+```ts
+import {Bytename} from "@e280/stz"
+```
+- ```ts
+  Bytename.fromBytes(new Uint8Array([0xDE, 0xAD, 0xBE, 0xEF]))
+    // "ribmug.hilmun"
+  ```
+- ```ts
+  Bytename.toBytes("ribmug.hilmun")
+    // Uint8Array, 4 bytes
+  ```
+- ```ts
+  const bytes = new Uint8Array([
+    0xDE, 0xAD, 0xBE, 0xEF,
+    0xDE, 0xAD, 0xBE, 0xEF,
+  ])
+
+  Bytename.fromBytes(bytes, {
+    groupSize: 2, // default is 4
+    groupSeparator: " ",
+    wordSeparator: ".",
+  })
+    // "ribmug.hilmun ribmug.hilmun"
+  ```
+
+<br/>
+
+## 💖 stz is made with open source love
+reward us with github stars  
+build with us at https://e280.org/ but only if you're cool  
+

package/package.json

@@ -1,28 +1,35 @@
 {
 	"name": "@e280/stz",
-	"version": "0.0.0-3",
+	"version": "0.0.0-30",
 	"description": "everyday ts fns for everything",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
 	"type": "module",
-	"main": "x/index.js",
+	"main": "./x/index.js",
+	"exports": {
+		".": "./x/index.js"
+	},
 	"files": [
 		"x",
 		"s"
 	],
 	"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 {} +",
+		"watch": "run-p _tscw test-watch",
 		"_clean": "rm -rf x && mkdir x",
 		"_links": "ln -s \"$(realpath node_modules)\" x/node_modules",
 		"_tsc": "tsc",
-		"start": "exit 0",
-		"count": "find s -path '*/_archive' -prune -o -name '*.ts' -exec wc -l {} +",
-		"test": "exit 0"
+		"_tscw": "tsc -w"
 	},
 	"devDependencies": {
-		"@types/node": "^22.14.1",
+		"@e280/science": "^0.0.5",
+		"@types/node": "^24.2.0",
 		"npm-run-all": "^4.1.5",
-		"typescript": "^5.8.3"
+		"typescript": "^5.9.2"
 	},
 	"keywords": [
 		"standard",

package/s/clone/clone.test.ts

@@ -1,124 +1,124 @@
-//
-// import {Suite, expect} from "cynic"
-// import {clone} from "./clone.js"
-//
-// function checkMapOrSetEquality(original: any, cloned: any) {
-// 	const originalEntries = JSON.stringify(Array.from(original))
-// 	const clonedEntries = JSON.stringify(Array.from(cloned))
-// 	expect(clonedEntries).equals(originalEntries)
-// 	expect(cloned).not.equals(original) // check for deep cloning
-// }
-//
-// export default <Suite>{
-//
-// 	async "clone primitive types"() {
-// 		expect(clone(123)).equals(123)
-// 		expect(clone("abc")).equals("abc")
-// 		expect(clone(true)).equals(true)
-// 	},
-//
-// 	async "clone arrays"() {
-// 		const array = [1, 2, 3]
-// 		const clonedArray = clone(array)
-// 		expect(JSON.stringify(clonedArray)).equals(JSON.stringify(array))
-// 		expect(clonedArray).not.equals(array) // check for deep cloning
-// 	},
-//
-// 	async "clone plain objects"() {
-// 		const object = {foo: "bar", baz: 123}
-// 		const clonedObject = clone(object)
-// 		expect(JSON.stringify(clonedObject)).equals(JSON.stringify(object))
-// 		expect(clonedObject).not.equals(object) // check for deep cloning
-// 	},
-//
-// 	async "clone Map"() {
-// 		const map = new Map()
-// 		map.set("key", "value")
-// 		const clonedMap = clone(map)
-// 		expect(map.get("key")).equals("value")
-// 		expect(clonedMap).not.equals(map)
-// 	},
-//
-// 	async "clone Set"() {
-// 		const set = new Set()
-// 		set.add("value")
-// 		const clonedSet = clone(set)
-// 		expect(clonedSet.has("value")).ok()
-// 		expect(clonedSet).not.equals(set)
-// 	},
-//
-// 	async "clone Date"() {
-// 		const date = new Date()
-// 		const clonedDate = clone(date)
-// 		expect(clonedDate.getTime()).equals(date.getTime())
-// 		expect(clonedDate).not.equals(date) // check for deep cloning
-// 	},
-//
-// 	async "clone objects with circular reference"() {
-// 		const object: any = {foo: "bar"}
-// 		object.self = object // create circular reference
-// 		let error: any
-// 		try {
-// 			clone(object)
-// 		} catch (e) {
-// 			error = e
-// 		}
-// 		expect(error).not.equals(undefined)
-// 		expect(error instanceof Error).ok()
-// 	},
-//
-// 	async "clone nested objects"() {
-// 		const object = {foo: "bar", inner: {baz: 123, deeper: {qux: true}}}
-// 		const clonedObject = clone(object)
-// 		expect(JSON.stringify(clonedObject)).equals(JSON.stringify(object))
-// 		expect(clonedObject).not.equals(object) // check for deep cloning
-// 		expect(clonedObject.inner).not.equals(object.inner) // check for deep cloning
-// 		expect(clonedObject.inner.deeper).not.equals(object.inner.deeper) // check for deep cloning
-// 	},
-//
-// 	async "clone array of objects"() {
-// 		const array = [{foo: "bar"}, {baz: 123}, {qux: true}]
-// 		const clonedArray = clone(array)
-// 		expect(JSON.stringify(clonedArray)).equals(JSON.stringify(array))
-// 		expect(clonedArray).not.equals(array) // check for deep cloning
-// 	},
-//
-// 	async "clone object with array"() {
-// 		const object = {foo: "bar", array: [1, 2, 3]}
-// 		const clonedObject = clone(object)
-// 		expect(JSON.stringify(clonedObject)).equals(JSON.stringify(object))
-// 		expect(clonedObject).not.equals(object) // check for deep cloning
-// 	},
-//
-// 	async "clone object with Map"() {
-// 		const map = new Map()
-// 		map.set("key", "value")
-// 		const object = {foo: "bar", map}
-// 		const clonedObject = clone(object)
-// 		expect(JSON.stringify(clonedObject.foo)).equals(JSON.stringify(object.foo))
-// 		checkMapOrSetEquality(object.map, clonedObject.map)
-// 	},
-//
-// 	async "clone object with duplicate sibling references"() {
-// 		const dupeObject = { id: 1, name: "H4CK3RM4N" }
-// 		const data = { obj1: dupeObject, obj2: dupeObject }
-//
-// 		let didThrow = false
-// 		let clonedData: typeof data = {} as typeof data
-//
-// 		try {
-// 			clonedData = clone(data)
-// 		}
-// 		catch (error) {
-// 			didThrow = true
-// 		}
-//
-// 		expect(didThrow).not.equals(true)
-// 		expect(clonedData.obj1).not.equals(clonedData.obj2)
-// 		expect(clonedData.obj1.id).equals(1)
-// 		expect(clonedData.obj1.name).equals("H4CK3RM4N")
-// 		expect(clonedData.obj2.id).equals(1)
-// 		expect(clonedData.obj2.name).equals("H4CK3RM4N")
-// 	},
-// }
+
+import {clone} from "./clone.js"
+import {Science, expect} from "@e280/science"
+
+function checkMapOrSetEquality(original: any, cloned: any) {
+	const originalEntries = JSON.stringify(Array.from(original))
+	const clonedEntries = JSON.stringify(Array.from(cloned))
+	expect(clonedEntries).is(originalEntries)
+	expect(cloned).not.is(original) // check for deep cloning
+}
+
+export default Science.suite({
+
+	async "clone primitive types"() {
+		expect(clone(123)).is(123)
+		expect(clone("abc")).is("abc")
+		expect(clone(true)).is(true)
+	},
+
+	async "clone arrays"() {
+		const array = [1, 2, 3]
+		const clonedArray = clone(array)
+		expect(JSON.stringify(clonedArray)).is(JSON.stringify(array))
+		expect(clonedArray).not.is(array) // check for deep cloning
+	},
+
+	async "clone plain objects"() {
+		const object = {foo: "bar", baz: 123}
+		const clonedObject = clone(object)
+		expect(JSON.stringify(clonedObject)).is(JSON.stringify(object))
+		expect(clonedObject).not.is(object) // check for deep cloning
+	},
+
+	async "clone Map"() {
+		const map = new Map()
+		map.set("key", "value")
+		const clonedMap = clone(map)
+		expect(map.get("key")).is("value")
+		expect(clonedMap).not.is(map)
+	},
+
+	async "clone Set"() {
+		const set = new Set()
+		set.add("value")
+		const clonedSet = clone(set)
+		expect(clonedSet.has("value")).ok()
+		expect(clonedSet).not.is(set)
+	},
+
+	async "clone Date"() {
+		const date = new Date()
+		const clonedDate = clone(date)
+		expect(clonedDate.getTime()).is(date.getTime())
+		expect(clonedDate).not.is(date) // check for deep cloning
+	},
+
+	async "clone objects with circular reference"() {
+		const object: any = {foo: "bar"}
+		object.self = object // create circular reference
+		let error: any
+		try {
+			clone(object)
+		} catch (e) {
+			error = e
+		}
+		expect(error).not.is(undefined)
+		expect(error instanceof Error).ok()
+	},
+
+	async "clone nested objects"() {
+		const object = {foo: "bar", inner: {baz: 123, deeper: {qux: true}}}
+		const clonedObject = clone(object)
+		expect(JSON.stringify(clonedObject)).is(JSON.stringify(object))
+		expect(clonedObject).not.is(object) // check for deep cloning
+		expect(clonedObject.inner).not.is(object.inner) // check for deep cloning
+		expect(clonedObject.inner.deeper).not.is(object.inner.deeper) // check for deep cloning
+	},
+
+	async "clone array of objects"() {
+		const array = [{foo: "bar"}, {baz: 123}, {qux: true}]
+		const clonedArray = clone(array)
+		expect(JSON.stringify(clonedArray)).is(JSON.stringify(array))
+		expect(clonedArray).not.is(array) // check for deep cloning
+	},
+
+	async "clone object with array"() {
+		const object = {foo: "bar", array: [1, 2, 3]}
+		const clonedObject = clone(object)
+		expect(JSON.stringify(clonedObject)).is(JSON.stringify(object))
+		expect(clonedObject).not.is(object) // check for deep cloning
+	},
+
+	async "clone object with Map"() {
+		const map = new Map()
+		map.set("key", "value")
+		const object = {foo: "bar", map}
+		const clonedObject = clone(object)
+		expect(JSON.stringify(clonedObject.foo)).is(JSON.stringify(object.foo))
+		checkMapOrSetEquality(object.map, clonedObject.map)
+	},
+
+	async "clone object with duplicate sibling references"() {
+		const dupeObject = { id: 1, name: "H4CK3RM4N" }
+		const data = { obj1: dupeObject, obj2: dupeObject }
+
+		let didThrow = false
+		let clonedData: typeof data = {} as typeof data
+
+		try {
+			clonedData = clone(data)
+		}
+		catch (error) {
+			didThrow = true
+		}
+
+		expect(didThrow).not.is(true)
+		expect(clonedData.obj1).not.is(clonedData.obj2)
+		expect(clonedData.obj1.id).is(1)
+		expect(clonedData.obj1.name).is("H4CK3RM4N")
+		expect(clonedData.obj2.id).is(1)
+		expect(clonedData.obj2.name).is("H4CK3RM4N")
+	},
+})
 

package/s/coalesce.ts

@@ -1,4 +1,5 @@
 
+/** return a single function that calls all the provided functions */
 export function coalesce<A extends any[] = []>(...fns: ((...a: A) => void)[]) {
 	return (...a: A) => fns.forEach(fn => fn(...a))
 }

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)
 	},
 })