@e280/stz 0.0.0-8 → 0.1.0

package/README.md

@@ -1,36 +1,80 @@
 
-# `@e280/stz`
-standard library of environment-agnostic typescript functions we use basically everywhere
+# 🏂 `@e280/stz`
+
+**stz** is e280's standard library of environment-agnostic typescript tools.
+
+it's our javascript toolkit.
+
+zero dependencies.
 
 <br/>
 
-## the tools
-stz has many more tools than documented below, see their [sourcecode here in s/](./s/)
+## 🧰 STZ PRIMITIVES
 
-### MapG — an extension of js Map with handy methods
-- `map.require`
-  ```ts
-  import {MapG} from "@e280/stz"
+### 🍏 MapG
+> extended js map
 
-  const map = new MapG<number, string>([
-    [1, "hello"],
-    [2, "world"],
-  ])
+```ts
+import {MapG} from "@e280/stz"
+
+const map = new MapG<number, string>([
+  [1, "hello"],
+  [2, "world"],
+])
+```
 
-  // throws error if the value is undefined
+- `map.require(key)` — returns the value for key — if missing, throw an error
+  ```ts
   const value = map.require(1)
+    // "hello"
   ```
-- `map.guarantee`
+- `map.guarantee(key, make)` — returns the value for `key` — if missing, run `make` to set the value and return it
   ```ts
-  // if the value is undefined, the new value "rofl" is set and returned
   const value = map.guarantee(3, () => "rofl")
+    // "rofl"
   ```
 
-### pub and sub — minimal ergonomic event system
+### 🍏 nap
+> sleep for some milliseconds
+
+```ts
+import {nap} from "@e280/stz"
+
+await nap(900)
+  // wait for 900 milliseconds
+```
+
+### 🍏 defer
+> defer the resolve/reject of a promise to the outside
+
+```ts
+import {defer} from "@e280/stz"
+
+const deferred = defer()
+```
+
+- resolve the deferred promise
+    ```ts
+    deferred.resolve()
+    ```
+- reject the deferred promise
+    ```ts
+    deferred.reject(new Error("fail"))
+    ```
+- await the promise
+    ```ts
+    await deferred.promise
+    ```
+
+### 🍏 `pub` and `sub`
+> ergonomic event emitters
+
+```ts
+import {pub, sub} from "@e280/stz"
+```
+
 - make a publisher fn
   ```ts
-  import {pub} from "@e280/stz"
-
   // create a pub fn
   const sendMessage = pub<[string]>()
 
@@ -42,8 +86,6 @@ stz has many more tools than documented below, see their [sourcecode here in s/]
   ```
 - 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]>()
 
@@ -72,14 +114,223 @@ stz has many more tools than documented below, see their [sourcecode here in s/]
   sendMessage.clear()
   onMessage.clear()
 
-  // you can subscribe to only one next call
-  onMessage.once(m => console.log(m))
-  sendMessage.once(m => console.log(m))
+  // instead of a 'once' fn we simply await next()
+  await onMessage.next()
+  await sendMessage.next()
+  ```
+
+<br/>
+
+## 🧰 STZ FN TOOLS
+
+### 🍏 `queue(fn)`
+> execute calls in sequence (not concurrent)
+
+```ts
+import {queue, nap} from "@e280/stz"
+
+const fn = queue(async() => nap(100))
+
+fn()
+fn()
+await fn() // waits for the previous calls (sequentially)
+```
+
+### 🍏 `once(fn)`
+> ensure a fn is only executed one time
+
+```ts
+import {once} from "@e280/stz"
+
+let count = 0
+const fn = once(() => count++)
+console.log(count) // 0
+
+fn()
+console.log(count) // 1
+
+fn()
+console.log(count) // 1
+```
+
+### 🍏 `deadline(100, fn)`
+> throws an error if the async function takes too long
+
+```ts
+import {deadline} from "@e280/stz"
+
+const fn = deadline(100, async() => {
+
+  // example deliberately takes too long
+  await nap(200)
+})
+
+await fn()
+  // DeadlineError: deadline exceeded (0.1 seconds)
+```
+
+### 🍏 `debounce(100, fn)`
+> wait some time before actually executing the fn (absorbing redundant calls)
+
+we use `debounce` a lot in ui code, like on a user's keyboard input in a form field, but rendering the form input can actually be slow enough that it causes problems when they type fast — to eliminate the jank, we `debounce` with like 400 ms, so we wait for the user to finish typing for a moment before actually running the validation.
+
+```ts
+import {debounce} from "@e280/stz"
+
+const fn = debounce(100, async() => {
+  await coolAction()
+})
+
+// each fn() call resets the timer
+fn()
+fn()
+fn()
+
+// coolAction is only called once here, other calls are redundant
+```
+
+### 🍏 `repeat(fn)`
+> execute a function over and over again, back to back
+
+```ts
+import {repeat} from "@e280/stz"
+
+let ticks = 0
+
+const stop = repeat(async() => {
+
+  // use a nap to add a delay between each execution
+  await nap(200)
+
+  ticks++
+})
+
+// stop repeating whenever you want
+stop()
+```
+
+<br/>
+
+## 🧰 STZ DATA UTILITIES
+
+### 🍏 Hex
+> convert to/from hexadecimal string format
+- `Hex.fromBytes(bytes)` — bytes to hex string
+- `Hex.toBytes(string)` — hex string to bytes
+- `Hex.random(32)` — generate random hex string (32 bytes)
+
+### 🍏 Base64
+> convert to/from base64 string format
+- `Base64.fromBytes(bytes)` — bytes to string
+- `Base64.toBytes(string)` — string to bytes
+- `Base64.random(32)` — generate random string (32 bytes)
+
+### 🍏 Base64url
+> convert to/from base64 string format
+- `Base64url.fromBytes(bytes)` — bytes to string
+- `Base64url.toBytes(string)` — string to bytes
+- `Base64url.random(32)` — generate random string (32 bytes)
+
+### 🍏 Base58
+> convert to/from base64 string format
+- `Base58.fromBytes(bytes)` — bytes to string
+- `Base58.toBytes(string)` — string to bytes
+- `Base58.random(32)` — generate random string (32 bytes)
+
+### 🍏 Txt
+> convert to/from utf8 string format
+- `Txt.fromBytes(bytes)` — bytes to string
+- `Txt.toBytes(string)` — string to bytes
+
+### 🍏 Bytes
+> utilities for dealing with Uint8Array
+- `Bytes.eq(bytesA, bytesB)` — check if two byte arrays are equal
+- `Bytes.random(32)` — generate crypto-random bytes
+
+### 🍏 BaseX
+> convert data into arbitrary data encodings
+- 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/>
 
 <br/>
 
-## 💖 made with open source love
+## 💖 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,31 +1,35 @@
 {
 	"name": "@e280/stz",
-	"version": "0.0.0-8",
+	"version": "0.1.0",
 	"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 --verbose",
+		"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.3",
+		"@e280/science": "^0.1.0",
+		"@types/node": "^24.3.0",
 		"npm-run-all": "^4.1.5",
-		"typescript": "^5.8.3"
+		"typescript": "^5.9.2"
 	},
 	"keywords": [
 		"standard",

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/constructor.ts

@@ -0,0 +1,15 @@
+
+export type Constructor<T extends {} = {}> = new(...args: any[]) => T
+
+export type Ctor<
+	Params extends any[] = any[],
+	Instance extends {} = {},
+> = new(...params: Params) => Instance
+
+export function denew<
+		Params extends any[] = any[],
+		Instance extends {} = {},
+	>(C: Ctor<Params, Instance>) {
+	return (...p: Params) => new C(...p)
+}
+

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